> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Use a connection's MCP server

Every AgentKit connection has its own MCP server with all of the connection's tools. Find its URL, mint a session token for a user and connect any MCP client.
Every AgentKit [connection](/agentkit/concepts/) has its own MCP server. It serves all of that connection's tools, and there is nothing to create: once the connection exists, so does its server. Mint a session token for a user, and any MCP client can call the connection's tools as that user.

## Choose a connection MCP server or a Virtual MCP server

| | Connection MCP server | [Virtual MCP server](/agentkit/mcp/overview/) |
| --- | --- | --- |
| Tools | Every tool of one connection | The tools you choose, from one or more connections |
| Setup | None | Create it once per agent role |
| URL | `<environment URL>/mcp/v3/connections/<connection name>` | The `mcp_server_url` returned when you create it |
| Session token | Minted for the connection | Minted for the server |

Use a connection MCP server when an agent works with one app and should see what that app offers. Use a Virtual MCP server when an agent needs a few tools from several apps, or you want to keep the tool list short. Both accept [read-only tokens](/agentkit/mcp/read-only-tokens/).

## Before you start

- An AgentKit [connection](/agentkit/connections/), and its name, such as `gmail`. The URL uses the name exactly as stored, including case.
- The user's `identifier`: your app's ID for that user, the same value you passed when they authorized the connection. [Choose an identifier](/agentkit/concepts/#choose-an-identifier) explains why it shouldn't be an email address.
- A client set up as in the [Quickstart](/agentkit/quickstart/): `actions` in Python, `scalekit` in Node.js. For cURL, get an access token and keep it in `TOKEN`:

  ```bash
  TOKEN=$(curl -sS "$SCALEKIT_ENVIRONMENT_URL/oauth/token" \
    -d grant_type=client_credentials \
    -d client_id="$SCALEKIT_CLIENT_ID" \
    -d client_secret="$SCALEKIT_CLIENT_SECRET" | jq -r .access_token)
  ```

1. ## Get the server URL

   In the dashboard, go to **AgentKit** > **Connections**, open the connection, and copy **MCP Server URL** from the **Configuration** tab. It has this form:

   ```text
   https://<your environment URL>/mcp/v3/connections/gmail
   ```

   You can also build it from your environment URL and the connection name. The path is case-sensitive, so use the name exactly as it appears in the dashboard.

2. ## Mint a session token

   Mint a token for the user before each run. Set `expiry` a little above how long the run takes: between 60 seconds and 24 hours, one hour by default.

   **Python**

   ```python
   from datetime import timedelta

   session = actions.mcp.create_session_token(
       connection_name="gmail",
       identifier="user_123",
       expiry=timedelta(minutes=15),
   )
   session_token = session.token
   ```

   **Node.js**

   ```ts
   const session = await scalekit.actions.mcp.createSessionToken({
     connectionName: 'gmail',
     identifier: 'user_123',
     expirySeconds: 900,
   });
   const sessionToken = session.token;
   ```

   **cURL**

   ```bash
   SESSION_TOKEN=$(curl -sS "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/connections/gmail/tokens" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"identifier": "user_123", "expiry": "900s"}' |
     jq -r .token)
   ```

   The token works only on this connection's server. To limit the agent to tools that don't change anything, add `access_level="READ_ONLY"` (Python) or `accessLevel: 'READ_ONLY'` (Node.js): see [Limit an agent to read-only tools](/agentkit/mcp/read-only-tokens/).

3. ## Connect the MCP client

   Give your MCP client the server URL and the header `Authorization: Bearer <session token>`. Most frameworks take them as the server's URL and headers. [Mint session tokens](/agentkit/mcp/session-tokens/#connect-the-mcp-client) shows the MCP SDK clients in Python and Node.js, and [Connect any MCP client](/agentkit/mcp/connect-any-client/) has the HTTP contract for everything else.

## Check it worked

List the tools with the token:

```bash
curl -sS "$SCALEKIT_ENVIRONMENT_URL/mcp/v3/connections/gmail" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' |
  sed -n 's/^data: //p' | jq -r '.result.tools[].name'
```

You see the connection's tools, such as `gmail_fetch_mails`, and `connect_account`. If the user hasn't authorized the connection yet, the agent calls `connect_account` to get an authorization link for them, as in [Connect a user's account from the agent](/agentkit/mcp/connect-any-client/#connect-a-users-account-from-the-agent).

## Common problems

### `404` when minting the token

No active connection has that name in this environment. Check the name in **AgentKit** > **Connections**, and that the connection is enabled.

### `400` when minting the token

The identifier or `expiry` is invalid, the connection isn't an AgentKit connection, or the user has no active account on the connection. In the last case, [send the user an authorization link](/agentkit/tools/authorize/) and mint again once the account is `ACTIVE`.

### `401` with `invalid or expired bearer token`

The token expired, was minted for a different server, or the URL's connection name differs from the stored name, for example in case. Copy the URL from the dashboard and mint a new token for this connection.

## Next

  - [Limit an agent to read-only tools](/agentkit/mcp/read-only-tokens/): Mint a token that can only read, on any MCP server.
  - [Mint session tokens](/agentkit/mcp/session-tokens/): Decide when to mint for scheduled, concurrent and long-running agents.

## API reference

The endpoints this page's code calls, with every field and the SDK method for each:

- `POST` [Mint a session token](https://docs.scalekit.com/agentkit/reference/virtual-mcp-servers/mint-a-session-token.md)
- `POST` [Mint a session token for a connection](https://docs.scalekit.com/agentkit/reference/virtual-mcp-servers/mint-a-connection-session-token.md)


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |