# Get started with Managed MCP Servers

Set up and use Managed MCP Servers with AI agents.

The following guide demonstrates how to set up and use Managed MCP Servers with AI agents. It is split into two sections:

- [Create the MCP Server](/api/managed-mcp-servers-get-started.md#create-the-mcp-server): covers creating an MCP Server configuration and retrieving the MCP Server URL.
- [Use the MCP Server with a client](/api/managed-mcp-servers-get-started.md#use-the-mcp-server-with-a-client): covers connecting this MCP Server to a client.

## Create the MCP Server

This section walks through creating an MCP Server configuration and retrieving its URL. To skip the manual steps, download the [Postman and Bruno collection](/api/downloads/managed-mcp-servers-postman-bruno.zip) to create and update MCP Servers. The included README explains how to import and use the collection.

### Create an API Client and get a bearer token

To create Managed MCP Servers, you must create an API Client with the `manage_mcp_servers:{projectKey}` scope. You can create the API Client in the Merchant Center or by using the [API Clients API](/api/projects/api-clients.md#create-api-client).

In the following example request body, replace `{projectKey}` with your Project key:

```json title="Request body"
{
  "name": "mcp-server-test",
  "scope": "manage_mcp_servers:{projectKey}"
}
```

In the response, note the `id`, `secret`, and `scope` values. Use these values to get a bearer token using the [Client credentials flow](/api/authorization.md#client-credentials-flow).

### Create an MCP Server configuration

When you create a Managed MCP Server configuration, you define which tools the AI agent can use. This example creates an MCP Server that can read Category and Product information.

For security and performance, only enable the tools required for your use case, instead of using `all`.

Using the bearer token you just obtained, send the following request body to the [Create MCP Server endpoint](/api/projects/managed-mcp-servers.md#create-mcp-server):

```json title="Request body for creating an MCP Server"
{
  "key": "my-mcp-server",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "tools": ["read_categories", "read_products"]
  }
}
```

The response includes the MCP Server URL in `mcpServer.url`. Note this URL, because you need it to connect your AI agent to the MCP Server.

You can also retrieve the MCP Server URL later using the [Get MCP Server by ID](/api/projects/managed-mcp-servers.md#get-mcp-server-by-id) or [Get MCP Server by key](/api/projects/managed-mcp-servers.md#get-mcp-server-by-key) endpoint.

## Use the MCP Server with a client

After the MCP Server is set up, an MCP client must authenticate before it can call any tools.
Both methods require you to first [create an API Client](/api/managed-mcp-servers-get-started.md#create-an-api-client-for-the-mcp-server). You can then authenticate in two ways:

- **Static bearer token**: fetch an access token yourself, then paste it into the client configuration.
  Use this option if your client does not support OAuth 2.0 discovery.
  See [Authenticate with a static bearer token](/api/managed-mcp-servers-get-started.md#authenticate-with-a-static-bearer-token).
- **OAuth 2.0 client credentials discovery**: use this option if your client supports the [OAuth Client Credentials Extension](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials).
  Your MCP client handles token exchange automatically. The API Client `id` is used as the OAuth `client_id`, and the API Client `secret` is used as the OAuth `client_secret`.
  See [Authenticate with OAuth 2.0 discovery](/api/managed-mcp-servers-get-started.md#authenticate-with-oauth-20-discovery).

The examples below show the static bearer token setup for [Claude Code](https://code.claude.com/docs/en), [Cursor](https://cursor.com/docs), and [n8n](https://docs.n8n.io/).
For other MCP clients, refer to your client's documentation.

### Create an API Client for the MCP Server

To create an API Client for the MCP Server, use the [API Clients API](/api/projects/api-clients.md#create-api-client) with the scope `mcp:{projectKey}:{mcpServerKey}`.

You can control the validity of the token with `accessTokenValiditySeconds`. The maximum validity for MCP Servers is 30 days (2592000 seconds).

In the following example request body, replace `{projectKey}` with your Project key and `{mcpServerKey}` with your MCP Server key:

```json title="Request body for creating an API Client for the MCP Server"
{
  "name": "mcp-server-client",
  "scope": "mcp:{projectKey}:{mcpServerKey}",
  "accessTokenValiditySeconds": 604800
}
```

In this example, the token validity is set to seven days (604800 seconds).

In the response, note the `id`, `secret`, and `scope` values.

### Authenticate with a static bearer token

Use the API Client's `id`, `secret`, and `scope` to get a bearer token using the [Client credentials flow](/api/authorization.md#client-credentials-flow).

The bearer token expires based on the `accessTokenValiditySeconds` value set when creating the API Client (maximum 30 days, or 2592000 seconds). To maintain connectivity after it expires, generate a new token using the same API Client credentials.

The scope allows only machine-to-machine interaction; it doesn't allow access to the Merchant Center or a specific Store.

#### Connect to Claude Code

Create or update `.mcp.json` in the root of your repository with the following content:

```json title="Server configuration for Claude Code"
{
  "mcpServers": {
    "managed-mcp-servers": {
      "type": "http",
      "url": "<your-mcp-server-url>",
      "headers": {
        "Authorization": "Bearer <your-ctp-token>"
      }
    }
  }
}
```

Restart Claude Code and your MCP Server will be available.

#### Connect to Cursor

Open **Settings** > **MCP** and add a new server with the following details:

```json title="Server configuration for Cursor"
{
  "mcpServers": {
    "managed-mcp-servers": {
      "type": "http",
      "url": "<your-mcp-server-url>",
      "headers": {
        "Authorization": "Bearer <your-ctp-token>"
      }
    }
  }
}
```

Restart Cursor and your MCP Server will be available.

#### Connect to n8n

1. In n8n, create a Bearer Auth credential with your API Client token.
2. Download the [n8n-example-categories.json](/api/downloads/n8n-example-categories.json) example workflow file.
3. Create a new workflow, then in the top right select **...** > **Import from file** to import the workflow file.
4. In the Fetch Categories node, assign the credential and replace the endpoint URL with your MCP Server URL.

To test the workflow, open the webhook URL in your browser: `https://<your-n8n-instance>/webhook/commerce-summary`. You should see a list of categories from your Project.

### Authenticate with OAuth 2.0 discovery

If your client supports the [OAuth Client Credentials Extension](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials), it handles the token exchange for you. You do not fetch or paste a token manually.

Configure your client with the MCP Server URL and the API Client credentials:

- The API Client `id` is the OAuth `client_id`.
- The API Client `secret` is the OAuth `client_secret`.

Your client discovers the authorization server and requests tokens automatically. For implementation examples, see the official [MCP TypeScript and Python SDKs](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials#sdk-examples).

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Overview](/api/managed-mcp-servers-overview.md)
- [Next page: API reference](/api/projects/managed-mcp-servers.md)
- [Search documentation and API specs](/search.md)