> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Connection MCP to agent sessions

> Replace the Connection MCP with a scoped agent session

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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/guides/agent-sessions#tenant) for more selector options.

To allow every action for an integration, replace the integration policy with `"*"`:

```json theme={null}
{
  "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`:

```text theme={null}
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](/docs/guides/agent-sessions#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](/docs/guides/agent-sessions) for connection selectors, toolsets, meta tools, session lifecycle, and MCP client examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.