Migrate from Connection MCP to agent sessions

The Connection MCP is deprecated. Agent sessions are its replacement for giving an agent access to Nango integrations. The main change is that your backend creates a scoped, expiring session for the agent. The session defines which connections and action functions the agent can use.

Main differences

Connection MCP uses an Environment API key and connection headers. Agent sessions use a session token.
Connection MCP selects one connection for a request. Agent sessions define their connection scope when created and can include multiple integrations.
Agent sessions use an explicit toolset to control which action functions are available.
Action functions are searchable by default instead of appearing directly in tools/list.
Session tool names include the integration ID, such as notion__read_doc instead of read_doc.
Agent sessions expire and cannot be extended.

Create an agent session

Create the session from your backend with an Environment API key that has the environment:agent_sessions:write scope. Pin the connection previously used by your Connection MCP integration and allow the action functions your agent needs:

curl --request POST \
  --url https://api.nango.dev/sessions \
  --header "Authorization: Bearer <NANGO-API-KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "tenant": {
      "connections": {
        "pinned": [
          {
            "integration_id": "<INTEGRATION-ID>",
            "connection_id": "<CONNECTION-ID>"
          }
        ]
      }
    },
    "toolset": {
      "<INTEGRATION-ID>": {
        "allow": {
          "tools": ["<ACTION-NAME>"]
        }
      }
    },
    "expires_in": "1h"
  }'

The response includes a session_token and mcp_url. You can select connections by tags instead of hardcoding a connection ID:

{
  "tenant": {
    "connections": {
      "any": [
        {
          "tags": {
            "user_id": "<USER-ID>"
          }
        }
      ]
    }
  }
}

Selectors must resolve to exactly one connection per integration. A session can include connections from multiple integrations. See Tenant for more selector options. To allow every action for an integration, replace the integration policy with "*":

{
  "toolset": {
    "<INTEGRATION-ID>": "*"
  }
}

The actions remain searchable by default; add them to pinned_tools if they must appear directly in tools/list.

Connect your agent to the session MCP

Configure your MCP client with the returned mcp_url and session_token:

URL: mcp_url
Authorization: Bearer session_token

You no longer need to send the Connection MCP headers:

connection-id
provider-config-key

Keep the Environment API key in your backend. Do not pass it to the agent.

Discover and call tools

Connection MCP listed available actions directly. To preserve that behavior, add the actions your agent relies on to pinned_tools when creating the session. Otherwise, leave them searchable, which is useful when the toolset is large. Searchable action functions can be used through:

nango_tool_search to find a relevant action function
nango_execute to run the selected action function

Update any system prompts or client configuration that refer to tools by name. For example, read_doc becomes notion__read_doc when it is exposed directly by a session. See Toolsets & tools for details.

Handle session expiry

Agent sessions expire according to expires_in. Create a new session when the current one expires. You can also terminate a session early when the agent task ends. See the agent sessions guide for connection selectors, toolsets, meta tools, session lifecycle, and MCP client examples.

Getting started

Guides

Reference

Migrate from Connection MCP to agent sessions

Main differences

Create an agent session

Connect your agent to the session MCP

Discover and call tools

Handle session expiry

​Main differences

​Create an agent session

​Connect your agent to the session MCP

​Discover and call tools

​Handle session expiry

Main differences

Create an agent session

Connect your agent to the session MCP

Discover and call tools

Handle session expiry