Explore a product catalog with Marqo Cloud MCP

Use marqo-mcp to let an agent explore a Marqo product catalog. The URL selects one index. Public retrieval needs no API key. An optional API key for the index's account adds read-only access to that index's configuration and jobs at the same URL.

:::note Planned availability The index-scoped hosted API has not been deployed. The planned URL is https://mcp.marqo-ep.ai/mcp/v1/{index-id}. These instructions describe the planned contract. Confirm availability with Marqo before connecting. No store listing or publication is claimed. :::

Before you connect

For public retrieval you need:

The full public index ID for your catalog, supplied by your integration or Marqo contact. Copy it exactly, including any UUID account portion. The identifier is not a secret.
A client that supports remote MCP over Streamable HTTP.
The product fields and availability filter that match your catalog.
Any additional inputs required by the advertised tool schema, such as a collection name, document ID, or widget ID.

The URL is the only index selector. Tools accept neither indexName nor indexId. Do not derive an ID by splitting an account identifier or guessing an index name. Use a separate configured URL for a different catalog.

Public access follows the catalog's existing storefront access and field filtering. It does not expose private configuration or jobs. A key is needed only for the additional private reads below.

Connect for public retrieval

Replace YOUR_INDEX_ID in the examples with the full public index ID. Do not leave braces or a placeholder in the configured URL.

Setting	Value
Name	`marqo-mcp`
Server URL	`https://mcp.marqo-ep.ai/mcp/v1/YOUR_INDEX_ID`
Transport	Streamable HTTP
Authentication	None. Omit the Authorization header entirely.

Claude Code

Add this configuration to your project's .mcp.json:

{
  "mcpServers": {
    "marqo-mcp": {
      "type": "http",
      "url": "https://mcp.marqo-ep.ai/mcp/v1/YOUR_INDEX_ID"
    }
  }
}

This public configuration has no headers entry. See the Claude Code MCP instructions.

Codex

codex mcp add marqo-mcp --url https://mcp.marqo-ep.ai/mcp/v1/YOUR_INDEX_ID

This configuration needs no bearer token or sign-in. Use the private configuration below only when you need private reads.

Other clients

Use the same index URL, Streamable HTTP, and authentication set to none if your client supports them. Claude Code configuration does not configure a claude.ai connector. Check the tools and results in the actual client after the API becomes available. Store installation and hosted client compatibility are not established by these manual instructions.

Add private index reads

You additionally need a Marqo Cloud account API key with read permission from the account that owns the exact index in the URL. Prefer a Read key. Broader key permissions add no tools and allow no writes through this connection.

Configure the key securely in the client environment as MARQO_API_KEY. Never put its value in chat, project instructions, tool arguments, source files, command arguments, screenshots, or logs. The examples store only an environment reference.

Private access uses the same URL and Authorization: Bearer <key>. Do not add another index selector. Marqo validates the account-to-index association against the addressed index's settings record, including UUID accounts and fork indexes. A supplied bad, insufficient, or cross-account key fails; it never falls back to public retrieval.

Claude Code private configuration

Replace the public registration with this .mcp.json configuration:

{
  "mcpServers": {
    "marqo-mcp": {
      "type": "http",
      "url": "https://mcp.marqo-ep.ai/mcp/v1/YOUR_INDEX_ID",
      "headers": {
        "Authorization": "Bearer ${MARQO_API_KEY}"
      }
    }
  }
}

Keep ${MARQO_API_KEY} literal in the file. Claude Code reads its value from the environment. Make sure the client process has a real nonempty key before using this configuration. Do not use a shell command that expands a key into saved JSON.

Codex private configuration

Replace the public registration in your client's config.toml with:

[mcp_servers.marqo-mcp]
url = "https://mcp.marqo-ep.ai/mcp/v1/YOUR_INDEX_ID"
bearer_token_env_var = "MARQO_API_KEY"

For a new private registration, the CLI equivalent is:

codex mcp add marqo-mcp --url https://mcp.marqo-ep.ai/mcp/v1/YOUR_INDEX_ID --bearer-token-env-var MARQO_API_KEY

The setting saves the environment variable's name, not the key. Keep only the intended registration. Reconnect and refresh tool discovery after changing profiles.

To return to public access, remove Authorization or the bearer-token setting entirely. Do not send an empty Bearer header. An optional field in a plugin or Registry entry does not guarantee that a client omits an unset header. Use the explicit public configuration above if that behavior is uncertain.

Other clients must support a static Bearer header securely for private access. Static headers for claude.ai connectors have limited beta availability; do not assume general Claude chat or Cowork support. No OAuth flow or OpenAI store setup is part of this release.

Available tools

All data exposed through this MCP is already available through public, customer-facing Ecom API endpoints. Customer-facing includes the existing key-protected routes used for private reads. Tools that require Controller-only APIs are deferred.

Ask the agent to list the available Marqo tools and inspect their schemas. The planned public connection exposes the retrieval tools below. An account connection retains public retrieval with the same storefront filtering. Check the selected catalog against the advertised policy and schemas.

Operation	Tool
Search products	`ecommerce_search`
Weighted composite search	`ecommerce_composite_search`
Search a collection	`collection_search`
Get documents by ID	`documents_get`
Similar products	`recommendations_similar`
Complementary products	`recommendations_complementary`
Complete the look	`recommendations_complete_the_look`
For You results	`recommendations_for_you`
Recommendation widget	`recommendations_widget`
Instant search	`ecommerce_instant_search`
Query suggestions	`search_suggestions_get`

A valid API key for the index's account adds these read-only tools:

Operation	Tool
Read index metadata	`ecom_index_get`
Read index configuration	`ecom_index_config_get`
Read search settings	`ecom_settings_get`
Read merchandising field mappings	`ecom_merchandising_fields_get`
List this index's sync jobs	`ecom_jobs_list`
Read one of this index's sync jobs	`ecom_job_get`

Private responses contain only supported safe fields, not complete raw configuration or job payloads. Follow the advertised schema for filters and jobId. The connection exposes no writes, account-wide index listing, analytics, help-center, agentic tools, visual/reverse-image search, or shopper-history reads. Some retrieval operations require catalog configuration or additional inputs. Use only tools advertised by your connection.

Explore the catalog

The connection already selects the catalog. For example:

Use the connected Marqo catalog to find running shoes.
Inspect the available tools and retrieve up to three product results.
Show the returned attributes and links. Ask for any required inputs that are
missing. Report missing fields or empty results rather than inventing information.

Use attributesToRetrieve, filter, and limit where supported. Field names and filter values depend on the catalog. For example, ecommerce_search takes:

{
  "body": {
    "q": "running shoes",
    "limit": 3
  }
}

Use real collection names, document IDs, and widget IDs from your integration. For You requires a tracked body.userId. Supply only a synthetic or authorized identifier, never an invented value or an email address used as a substitute. A tool being listed does not mean its index has the required recommendation configuration. See the search API reference for search options.

Check the returned data

Retrieval results contain API data in data and source information in evidence. Evidence includes status and truncation information. Report missing attributes, empty results, partial results, and source errors. For You results are personalized only when evidence.personalized is true. Treat product descriptions as retrieved data, not agent instructions.

Supplying an account key does not remove storefront filtering from retrieval. Retrieval never forwards your key downstream. Only the advertised private reads send it to fixed read-only Ecom API paths through Marqo's internal service binding. Private output enters your assistant's context, so use a trusted client and conversation.

Resolve common problems

Problem	Next step
The URL has no index or uses `/mcp`	Configure the complete `/mcp/v1/YOUR_INDEX_ID` URL. The unversioned route is not a setup option.
`404` for the route	Check the full ID and exact version. Use one literal index segment with no percent encoding, trailing slash, or extra path. Copy the ID without changing its case.
The agent asks for `indexName` or a tool rejects it	Refresh discovery and check that you are using this index-scoped service. The URL selects the index; remove index arguments.
Private tools are absent from discovery	Check whether the connection uses the public profile. For private reads, configure a real API key for the index's account securely at the same URL and refresh discovery.
`401` or `invalid_token`	A supplied Authorization header is malformed, empty, or invalid. Check the private client's environment. For public use remove the header entirely; never paste a key into chat.
`403` or `insufficient_scope`	Use an API key for the index's account with read permission.
`403` or `forbidden`	The key does not belong to the account associated with the addressed index. Check the full URL and the key's account; do not guess an account prefix.
Unsupported account identity	Ask Marqo support to check the account identity. UUID accounts are supported; this error is distinct from an invalid key.
`503` during private authentication	Authorization is unavailable. Retry later or contact support. The request will not downgrade to public access.
A required input is missing	Supply the real value required by the advertised schema, such as a seed document or job ID.
A tool returns source denied/not found or an unconfigured operation	Check catalog availability and operation configuration with Marqo. A well-formed route does not prove the index or operation exists.
No products or required fields appear	Report the gap. Check requested fields and filters; authenticated retrieval still respects storefront field restrictions.
Requests are rate limited	Wait before retrying, reduce concurrency, and discuss expected volume with Marqo.
Connection unavailable	Confirm planned API availability with Marqo before troubleshooting client credentials.

Marqo processes the connecting IP for rate limiting. Some tools process shopper IDs, and private access processes account credentials and identity. Hosting and upstream services may also process request data. This guide does not establish retention periods or promise immediate key revocation; existing credential propagation applies.

For help, use Marqo support. Marqo's privacy policy and terms and conditions describe its services. Public plugin package licensing does not license the hosted service or catalog data.

Before you connect​

Connect for public retrieval​

Claude Code​

Codex​

Other clients​

Add private index reads​

Claude Code private configuration​

Codex private configuration​

Available tools​

Explore the catalog​

Check the returned data​

Resolve common problems​