Use a connection's MCP server

Every AgentKit connection 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.

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.

• An AgentKit connection, 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 explains why it shouldn’t be an email address.

• A client set up as in the Quickstart: actions in Python, scalekit in Node.js. For cURL, get an access token and keep it in TOKEN:

  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

   Section titled “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:

   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

   Section titled “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
   • Node.js
   • cURL

   from datetime import timedelta
   
   session = actions.mcp.create_session_token(
       connection_name="gmail",
       identifier="user_123",
       expiry=timedelta(minutes=15),
   )
   session_token = session.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.

3. Connect the MCP client

   Section titled “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 shows the MCP SDK clients in Python and Node.js, and Connect any MCP client has the HTTP contract for everything else.

List the tools with the token:

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.

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

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 and mint again once the account is ACTIVE.

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.