Agent sessions

Agent sessions are an optimized interface for AI agents to use integrations. Each session has three parts:

Tenant — on whose behalf the agent can call integrations
Toolset — which integrations and tools it can use
Discovery — how it finds and calls those tools

Your backend creates the session and exposes it to the agent as an MCP server. The agent never sees raw credentials, and cannot change the scope of its own session. Example sessions:

A sales agent with a user’s personal Gmail & Google Calendar, and a read-only org-wide Salesforce connection
A finance agent with a few read-only tools on an org’s accounting system, and read & write access to a team’s Slack
A developer agent with a team’s Linear access and a user’s personal GitHub access

We are quickly expanding agent sessions, follow our changelog for announcements and improvements!

Quickstart

Create a session from your backend

By default, a session covers every tool on the integrations the tenant has a connection for.To define the tenant, select the connections the agent may use with tag selectors:

curl --request POST \
  --url 'https://api.nango.dev/sessions' \
  --header 'Authorization: Bearer <NANGO-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "tenant": {
      "connections": {
        "any": [{ "tags": { "organization_id": "acme", "workspace": "marketing" } }]
      }
    }
  }'

Requires an API key with the environment:agent_sessions:write scope. See API key scopes.This returns a ready-to-use session:

{
  "data": {
    "session_id": "0f4a...",
    "session_token": "nango_agent_session_...",
    "mcp_url": "https://api.nango.dev/session/0f4a.../mcp",
    "expires_at": "2026-09-15T10:00:00.000Z",
    "toolset": {
      "notion": { "connected": true, "tools_pinned": 0, "tools_searchable": 12 },
      "slack": { "connected": true, "tools_pinned": 0, "tools_searchable": 7 }
    },
    "meta_tools": { "nango_tool_search": true, "nango_execute": true, "nango_proxy": false }
  }
}

Pass the MCP server to your agent

Pass the mcp_url to your agent, with the session_token as bearer auth:

OpenAI
Anthropic
Vercel AI SDK
LangChain
Mastra

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6",
  input: "Summarize the last 5 emails in the user's inbox",
  tools: [
    {
      type: "mcp",
      server_label: "nango", // Or a name suitable for your session
      server_url: "<mcp_url>",
      authorization: "<session_token>",
      require_approval: "never"
    }
  ]
});

console.log(response.output_text);

The Responses API never stores the authorization value, so send it on every request.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Summarize the last 5 emails in the user's inbox" }],
  mcp_servers: [
    {
      type: "url",
      name: "nango",
      url: "<mcp_url>",
      authorization_token: "<session_token>"
    }
  ],
  tools: [{ type: "mcp_toolset", mcp_server_name: "nango" }],
  betas: ["mcp-client-2025-11-20"]
});

console.log(message.content);

The MCP connector is behind the mcp-client-2025-11-20 beta.

import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";

const mcpClient = await createMCPClient({
  transport: {
    type: "http",
    url: "<mcp_url>",
    headers: { Authorization: "Bearer <session_token>" }
  }
});

try {
  const { text } = await generateText({
    model: openai("gpt-5.6"),
    prompt: "Summarize the last 5 emails in the user's inbox",
    tools: await mcpClient.tools(),
    stopWhen: stepCountIs(10)
  });

  console.log(text);
} finally {
  await mcpClient.close();
}

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({
  mcpServers: {
    nango: {
      transport: "http",
      url: "<mcp_url>",
      headers: { Authorization: "Bearer <session_token>" }
    }
  }
});

const agent = createAgent({
  model: "openai:gpt-5.6",
  tools: await client.getTools()
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Summarize the last 5 emails in the user's inbox" }]
});

console.log(result.messages.at(-1)?.content);

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  id: "nango-session",
  servers: {
    nango: {
      url: new URL("<mcp_url>"),
      requestInit: {
        headers: { Authorization: "Bearer <session_token>" }
      }
    }
  }
});

const agent = new Agent({
  name: "Integrations agent",
  instructions: "Use the Nango tools to complete the user's request.",
  model: openai("gpt-5.6"),
  tools: await mcp.getTools()
});

const response = await agent.generate("Summarize the last 5 emails in the user's inbox");

console.log(response.text);

Give each session’s client a distinct id if you create one per request.

Your agent can now use every tool the session exposes.

Session basics

Creating a session

Create a session with the tools and access your agent needs.

{
  "tenant": {
    "connections": {  // Either "any" or "pinned" is required
      "any": [
        { "tags": { "endUserId": 74, "organizationId": "7283" }},
        { "tags": { "endUser": 74, "workspaceSlug": "slack-marketing-workspace" }}
      ],
      "pinned": [
        { "integration_id": "notion", "connection_id": "882386f9-efae-48aa-bea1-58a4f6fbc2ff" }
      ]
    }
  },

  "toolset": {       // Optional, defaults to all integrations
    "notion": { "allow": { "tools": ["read_doc", "upsert_doc"] } },
    "slack": "*"
  },
 
  "pinned_tools": {  // Optional, defaults to no pinned tools
    "notion": ["read_doc"]
  },

  "meta_tools": {    // Optional. nango_proxy is off unless you turn it on
    "nango_tool_search": true,
    "nango_execute": true,
    "nango_proxy": false
  },

  "expires_in": "1h" // Optional. Minimum "60s", maximum and default "15d".
}

Creation fails if your tenant selectors are not unique, or if a toolset or tool doesn’t exist in your Nango environment. Each session gets a unique session_id and session_token. The token is a scoped access token for that session — treat it as a secret, and keep session durations as short as your use case allows.

Session MCP server

Every session exposes its own MCP server at its mcp_url. It speaks Streamable HTTP and authenticates with the session_token as a bearer token, so any MCP-capable agent or client can connect to it. tools/list returns the enabled meta tools plus the pinned tools, paginated 50 at a time through nextCursor. Searchable tools are callable but not listed, and the agent finds them with the nango_tool_search meta tool.

Terminating a session

Sessions are immutable and cannot be extended. They expire on their own once expires_in is up, and you can end one early with DELETE /sessions/{session_id}:

curl --request DELETE \
  --url 'https://api.nango.dev/sessions/0f4a...' \
  --header 'Authorization: Bearer <NANGO-API-KEY>'

Requires an API key with the environment:agent_sessions:write scope, the same one session creation uses.

{
  "data": {
    "session_id": "0f4a...",
    "ended_at": "2026-09-15T10:00:00.000Z",
    "reason": "terminated"
  }
}

Terminating revokes the session_token together with the session, so the session’s MCP server answers 401 from that point on. A tool call already in flight is not cancelled. Terminating is idempotent. A session that has already ended keeps its original ended_at and reason, so terminating it again returns the same response. An unknown session, or one from another environment, returns a 404. Recreate the session with the same parameters if you need it again.

Tenant

The tenant defines on whose behalf the agent may act. For example: use a specific user’s Gmail credentials, but the org-wide credentials for Salesforce. You express this with Connection tag selectors under any, which the session resolves to the right Connections in Nango. Tags within one entry are ANDed, entries are ORed, up to 10 entries. Here, organization_id, workspace, and user_id are Connection tags we set up for our application.

{
  "tenant": {
    "connections": {
      "any": [
        { "tags": { "organization_id": "acme", "workspace": "marketing" } },
        { "tags": { "user_id": "27382" } }
      ]
    }
  }
}

Selectors must resolve to exactly one connection per integration at creation time. The resolved connection is stored on the session, and every tool call the agent makes afterwards uses it.

Resolving ambiguity

If the selectors match two or more connections on the same integration, there is no way to tell which one the session should use. Creation fails with ambiguous_connections, and no session is created:

{
  "error": {
    "code": "ambiguous_connections",
    "message": "1 integration matched more than one connection. Narrow the connection tags or pin a connection id.",
    "payload": {
      "integrations": {
        "notion": {
          "match_count": 2,
          "candidates": [{ "connection_id": "3fd0cc49-..." }, { "connection_id": "f91890c5-..." }]
        }
      }
    }
  }
}

There are two ways to resolve this:

Add tags to the selector until it matches exactly one connection per integration.
Use pinned to name the connection to use for that integration.

{
  "tenant": {
    "connections": {
      "any": [{ "tags": { "organization_id": "acme" } }],
      "pinned": [{ "integration_id": "notion", "connection_id": "f91890c5-..." }]
    }
  }
}

You can only use one pin per integration. A pin must be one of the connections the selectors matched, or creation fails with pinned_connection_not_matched. Pinning a connection that does not exist fails with unknown_pinned_connection. You can also use pinned without any any selectors, if you already know the exact connections you want to use. An integration that matches no connection does not fail creation. It appears in the toolset as connected: false, and its tool calls fail with a missing authorization error.

Currently there is no way for the agent to ask the user to connect an unconnected integration. Let us know if you need this and we are happy to prioritize it.

Toolsets & tools

toolset defines which tools are available to the agent. The toolset is a subset of the Integrations that are enabled in your Nango environment.

{
  "toolset": {
    "notion": { "allow": { "tools": ["read_doc", "upsert_doc"] } },
    "slack": "*"
  }
}

You can use the following selectors:

"*" on an integration means every action function on it
allow makes the integration an allowlist, where "*" means every tool
deny always subtracts from whatever allow gave
To deny an integration entirely, leave it out of the toolset
toolset: "*" at the top level means every integration in the environment
Leaving toolset out entirely means every integration the tenant resolved a connection for, which is narrower than "*"

Only action functions can be tools. Naming a sync fails with unsupported_function_type, an unknown integration with unknown_integration, and an unknown tool with unknown_tool. Any error fails creation, so a session is either fully valid or not created.

Pinned tools

By default, everything in the toolset is searchable with the nango_tool_search meta tool, but none of it is listed in the MCP server’s tool list. This keeps a large toolset from filling the agent’s context with hundreds of definitions it will never call. pinned_tools exposes specific tools in that list, so they are in context as soon as the agent loads the server:

{
  "toolset": { "notion": { "allow": { "tools": ["read_doc", "upsert_doc"] } } },
  "pinned_tools": { "notion": ["read_doc"] }
}

A pinned tool must be in the toolset, otherwise creation fails with tool_not_in_toolset.

Meta tools

Meta tools are Nango’s own tools. They are always pinned to the MCP server’s tool list.

Tool	What it does
`nango_tool_search`	Finds tools in the session’s toolset from a plain-language description
`nango_execute`	Runs one of the session’s tools by name
`nango_proxy`	Makes an authenticated request to a provider API, for when no tool fits

nango_tool_search and nango_execute default to true, nango_proxy to false. Set them on session creation with meta_tools:

{ "meta_tools": { "nango_execute": false, "nango_proxy": true } }

nango_tool_search

Takes a plain-language query describing what the agent wants to do.

{ "query": "find emails by subject" }

The result carries guidance for the agent, matches for the best hits, and related tools for weaker matches to narrow down. Each match names the tool to pass to nango_execute, its integration, action, and provider, whether it is listed, and its connection status. Only a best match includes input, its argument schema — a weak match is a lead, not something to call yet.

nango_execute

Runs one of the session’s tools by name, on the connection the session resolved for that integration.

{ "tool": "notion__read_doc", "input": { "doc_id": "abc" } }

Execution is synchronous and goes through the same path as triggering an action function, so it is capped by the synchronous execution limit and appears in Nango logs like any other function run.

nango_proxy

The escape hatch for when no tool in the session covers what the agent needs. It makes an authenticated HTTP request to a provider API on the connection the session resolved for that integration, so the agent names an integration and never a connection.

{ "integration": "notion", "method": "POST", "path": "/v1/search", "body": { "query": "roadmap" } }

It also takes query_params and headers. Nango authenticates the request from the session’s connection, so credential headers are rejected rather than forwarded, including the provider’s own (x-api-key and the like) alongside authorization. The integration has to be one in the session’s toolset with a resolved connection, but the path is not restricted to what the toolset exposes. That is why nango_proxy is off by default: turning it on lets the agent reach any endpoint of a connected integration. The result is the provider’s status, headers and body, for JSON or UTF-8 text responses up to 5 MB. Binary and larger responses are not supported, and neither is file upload. Use the HTTP proxy for those.

Getting started

Guides

Reference

Quickstart

Session basics

Creating a session

Session MCP server

Terminating a session

Tenant

Resolving ambiguity

Toolsets & tools

Pinned tools

Meta tools

nango_tool_search

nango_execute

nango_proxy

​Quickstart

​Session basics

​Creating a session

​Session MCP server

​Terminating a session

​Tenant

​Resolving ambiguity

​Toolsets & tools

​Pinned tools

​Meta tools

​nango_tool_search

​nango_execute

​nango_proxy

Quickstart

Session basics

Creating a session

Session MCP server

Terminating a session

Tenant

Resolving ambiguity

Toolsets & tools

Pinned tools

Meta tools

nango_tool_search

nango_execute

nango_proxy