Select integrations and tools
Settoolset when you create the session. Use integration IDs as keys and specify which tools to include for each one.
"*"on an integration means every tool on it (or every tool of its MCP server)allowmakes the integration an allowlist, where"*"means every tooldenyalways subtracts from whateverallowgave- To deny an integration entirely, leave it out of the toolset
toolset: "*"at the top level means every integration in the environment- Leaving
toolsetout entirely means every integration the tenant resolved a connection for, which is narrower than"*"
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 thenango_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:
tool_not_in_toolset.
MCP server tools
Integrations for MCP servers, such as Notion (MCP) or Linear (MCP), bring the server’s own tools into the session. Include the integration in the toolset like any other and give the tenant a connection to it. When the session is created, Nango lists the tools of each connected MCP server in the toolset and adds them alongside its Nango tools. From then on they work like any other tool:nango_tool_searchfinds them, with the input schema the server gave- Pinned, they are listed with that input schema and the server’s annotations
- Calling one by its listed name or through
nango_executeruns it on the server, on the session’s connection, and returns the server’s result as is
allow, deny and pinned_tools name a tool exactly as the server lists it. In the session, the tool gets a name like a Nango tool’s, such as notion-mcp__notion-search. Agents call it by the name the tool list or nango_tool_search gives.
The list is taken once, at creation. Tools the server adds or removes afterwards don’t change the session, so create a new one to pick them up.
When a server can’t be listed
A server that fails or does not answertools/list within 10 seconds does not fail session creation. The session is created without that server’s tools, and the toolset summary says so with mcp_server:
mcp_server is only present for integrations with a connected MCP server.
Running MCP server tools
Every call goes through the Nango proxy, so Nango applies and refreshes the connection’s credentials, and the call shows up in Nango logs as a proxy operation. A result the server marks withisError reaches the agent unchanged. When the call itself fails, the agent gets an error that says what to do next:
- Timeout: a tool has 60 seconds to answer. The agent is told it may still have run, so it checks before calling again.
- Too large: results are capped at 5 MB. The agent is told to narrow its input.
- Refused: a
403on one tool, for example a missing OAuth scope, fails that tool only. A401, or a403before any tool runs, means the connection needs reconnecting, see reconnecting a connection.