Skip to content
Truto
Truto Blog
Back
AI & Agents

Connect Nango to Claude: Build Functions & Execute API Actions

Learn how to connect Nango to claude using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Roopendra Talekar Roopendra Talekar · · 10 min read
Connect Nango to Claude: Build Functions & Execute API Actions

If your team needs to connect Nango to Claude to automate integration deployments, orchestrate data syncs, or execute third-party proxy requests, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Nango's REST API infrastructure. You can either build and maintain this translation layer yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Nango to ChatGPT or explore our broader architectural overview on connecting Nango to AI Agents.

Giving a Large Language Model (LLM) read and write access to an integration platform like Nango is a meta-engineering challenge. You are not just managing one API - you are managing an API that manages other APIs. You have to handle connection states, provider configurations, custom function deployments, and opaque proxy responses. Every time Nango introduces a new bulk endpoint or deprecates a legacy metadata path, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Nango, connect it natively to Claude, and execute complex integration workflows using natural language.

The Engineering Reality of the Nango API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Nango's API is complex. Nango is designed to abstract third-party APIs, meaning its own API surface is highly dynamic and context-dependent.

If you decide to build a custom Nango MCP server, here are the specific integration challenges you will face:

The Provider Config Key Requirement Almost every operational endpoint in Nango - whether triggering a sync, updating metadata, or executing an action - requires both a connection_id and a provider_config_key. A naive MCP implementation might just expose connection_id to the LLM, expecting it to function like a standard primary key. It does not. If an LLM attempts to fetch credentials or trigger an action without explicitly passing the provider_config_key tied to that specific integration setup, the request will fail. A managed MCP server enforces this dual-key requirement strictly in the JSON Schema of its tools, preventing the model from hallucinating incomplete requests.

Legacy Metadata vs Bulk Update Endpoints Nango is currently transitioning from legacy path-based connection endpoints (like /connection/metadata) to standardized bulk update endpoints. If you give an LLM raw access to the OpenAPI spec, it will frequently attempt to use deprecated single-connection metadata endpoints, often overwriting entire metadata objects when it only meant to patch a single field. Truto handles this by exposing curated tools like nango_connections_bulk_update that explicitly support partial overrides, shielding the LLM from destructive legacy endpoints.

Opaque Passthrough Proxying Nango's proxy endpoints (e.g., list_all_nango_proxy or create_a_nango_proxy) accept a URL path and forward requests to third-party APIs. The response returned is entirely opaque - it is exactly what the external API returned, complete with third-party headers and varied JSON structures. LLMs struggle with unpredictable response schemas. The MCP tool must explicitly instruct the LLM on how to interpret these opaque passthroughs based on the target integration, ensuring the model knows it is parsing external vendor data rather than standard Nango responses.

Rate Limits and 429 Handling Nango rate limits API requests based on plan tiers. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors automatically. When Nango returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (the AI agent or the human operating the LLM framework) is entirely responsible for observing these headers and implementing their own retry and backoff logic.

Generating the Nango MCP Server

Truto derives MCP tools dynamically from Nango's integration resources and documentation. Rather than hand-coding tool definitions, Truto uses the integration's documented endpoints to generate descriptive tool names, query schemas, and body schemas. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring only curated, well-tested endpoints are exposed to Claude.

You can create an MCP server for Nango using either the Truto UI or the API.

Method 1: Via the Truto UI

For teams who prefer a visual workflow, you can generate a persistent MCP server directly from the dashboard.

  1. Navigate to the Integrated Accounts page in your Truto dashboard.
  2. Select your connected Nango account.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration. You can filter by specific methods (e.g., only read operations) or tags (e.g., only proxy or sync tools), and set an optional expiration date.
  6. Copy the generated MCP server URL. This URL contains the cryptographic token needed to authenticate your connection.

Method 2: Via the Truto API

For automated provisioning - such as generating temporary MCP servers for ephemeral AI agent sessions - you can use the Truto REST API.

Make a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/<your_nango_integrated_account_id>/mcp \
  -H "Authorization: Bearer <your_truto_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nango Agent Server",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The response will return the configuration and the ready-to-use MCP URL:

{
  "id": "mcp_abc123",
  "name": "Nango Agent Server",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/tkn_789xyz..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, connecting it to Claude takes less than a minute. You can do this via the Claude desktop application interface or by manually editing the configuration file.

Method A: Via the Claude UI

(Note: If you are connecting this to ChatGPT instead, the process is similar: Settings -> Apps -> Advanced settings -> Developer mode -> Add custom connector)

  1. Open the Claude Desktop application.
  2. Navigate to Settings -> Integrations -> Add MCP Server.
  3. Enter a recognizable name (e.g., "Nango Operations").
  4. Paste the Truto MCP server URL into the URL field.
  5. Click Add. Claude will automatically perform the JSON-RPC initialization handshake and discover all available Nango tools.

Method B: Via Manual Config File

For headless deployments, CI/CD environments, or advanced local setups, you can add the server directly to your claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) wrapper to proxy HTTP requests for local clients.

{
  "mcpServers": {
    "nango_ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/tkn_789xyz..."
      ]
    }
  }
}

Restart Claude Desktop, and the model will immediately have access to your Nango workspace.

Hero Tools for Nango

When Claude connects to the Nango MCP server, it gains access to dozens of dynamically generated tools. Here are the highest-leverage hero tools for automating integration infrastructure.

list_all_nango_connections

This tool retrieves all active Nango connections across your integration catalog. It provides the essential connection_id and provider_config_key pairs required for subsequent operations.

Usage note: Use this tool to audit which tenants have connected which third-party applications, and to inspect high-level connection metadata and error states before running actions.

"Claude, list all active connections for the HubSpot provider. Tell me if any of them are currently in an error state, and output their connection IDs and provider config keys."

nango_connections_bulk_update

Updates custom metadata for one or more Nango connections using a partial override. This is the modern, safe way to update connection states without overwriting the entire metadata JSON object.

Usage note: Pass an array of connection IDs to update multiple connections simultaneously. If any ID is invalid, the operation safely aborts without making partial changes.

"Claude, update the metadata for connection ID 'tenant-456' under the provider config key 'hubspot-oauth'. Add a new metadata property called 'sync_priority' and set it to 'high'."

nango_functions_create_deployment

Deploys a custom function to a Nango integration using TypeScript source code or a pre-built provider template.

Usage note: This tool allows Claude to literally write, submit, and deploy custom integration glue code dynamically. The tool triggers an asynchronous deployment; the model must check the resulting deployment ID for success.

"Claude, deploy a new custom function for the 'salesforce-sync' integration. Here is the TypeScript code that parses custom fields. Name the function 'parse_custom_fields' and set the type to 'function'."

nango_sync_start

Starts the schedule of specified data syncs for a given connection. If the sync is already running, it has no effect. The sync executes immediately and continues at its configured frequency.

Usage note: This is critical for activating data pipelines after a user successfully authenticates a new connection.

"Claude, start the 'fetch_contacts' and 'fetch_deals' syncs for the Salesforce connection with ID 'acme-corp'. The provider config key is 'salesforce-prod'."

list_all_nango_records

Lists synced records from a specific Nango data model, returning the normalized data structured by your Nango integration configurations.

Usage note: This tool retrieves the actual payload of synced data. It paginates via cursor. Be prepared for large payloads and instruct Claude to filter or summarize the output.

"Claude, list the most recent synced records for the 'contacts' data model. Extract the email addresses and names from the response and format them into a markdown table."

create_a_nango_proxy

Forwards a POST request directly to a third-party API through the Nango proxy, automatically injecting the correct authenticated connection tokens.

Usage note: This tool bypasses Nango's sync engine and executes direct writes to downstream platforms. The response is opaque, meaning Claude will need to interpret the raw third-party JSON payload returned.

"Claude, execute a POST proxy request to the Slack integration for connection 'slack-team-x'. Send a message payload to the '#alerts' channel using the standard Slack Chat.PostMessage format."

nango_actions_trigger

Triggers a predefined action configured in your Nango integration dashboard. Actions run custom logic or external API calls securely.

Usage note: Actions can be triggered synchronously (returning data up to 10MB) or asynchronously. Use this for operations that require complex logic already built and deployed in Nango.

"Claude, trigger the 'create_invoice' action for the Xero connection 'billing-org-1' using the 'xero-partner' provider config key. Pass the invoice amount and contact details in the body."

For the complete inventory of Nango tools, parameter schemas, and return types, review the Nango integration page.

Workflows in Action

By chaining these tools together, Claude can execute complex, multi-step integration management tasks autonomously.

sequenceDiagram
    participant User
    participant Claude as Claude (AI Agent)
    participant Truto as Truto MCP Server
    participant Nango as Nango API
    participant Upstream as Upstream API (Salesforce)

    User->>Claude: "Find broken Salesforce connections and run a proxy check."
    Claude->>Truto: Call list_all_nango_connections
    Truto->>Nango: GET /connection
    Nango-->>Truto: Return connections with errors
    Truto-->>Claude: JSON Array
    Claude->>Truto: Call list_all_nango_proxy (for broken connection)
    Truto->>Nango: GET /proxy/salesforce/limits
    Nango->>Upstream: GET /services/data/v58.0/limits
    Upstream-->>Nango: 200 OK (Limit data)
    Nango-->>Truto: Opaque Passthrough Response
    Truto-->>Claude: JSON Proxy Result
    Claude-->>User: "Found 1 broken connection. Proxy check succeeded. Metadata updated."

Scenario 1: Auditing and Repairing Stalled Syncs

Integration managers frequently need to track down why a specific customer's data pipeline has stopped moving. Claude can investigate the connection, check the sync status, and restart the schedule if necessary.

"Claude, find the connection for the tenant 'Stark Industries' using the 'hubspot-oauth' provider. Check the status of their 'fetch_tickets' sync. If it is paused or failed, attempt to start the sync schedule again."

Execution Steps:

  1. Claude calls list_all_nango_connection to search for connections belonging to 'Stark Industries', extracting the connection_id and provider_config_key.
  2. Claude calls nango_sync_get_status using those identifiers and specifying the 'fetch_tickets' sync.
  3. Identifying that the sync status is 'paused', Claude calls nango_sync_start to resume the pipeline.

Result: The user receives a brief summary stating that the connection was found in a paused state, and the ticket sync has been successfully reactivated.

Scenario 2: Deploying a Custom Function and Updating Metadata

Developers building custom logic in Nango often bounce between their IDE, the Nango dashboard, and API clients. Claude can act as a fully integrated DevOps assistant for Nango environments.

"Claude, I need to deploy a custom TypeScript function that formats inbound webhooks for our 'slack-bot' provider. Deploy this code block as a function named 'format_slack_webhook'. Once deployed, bulk update the metadata on all active 'slack-bot' connections to include 'webhook_version': 'v2'."

Execution Steps:

  1. Claude calls nango_functions_create_deployment, passing the provided TypeScript code, the function name, and specifying the 'slack-bot' integration.
  2. Claude calls list_all_nango_connections filtered by the 'slack-bot' provider to gather an array of active connection IDs.
  3. Claude calls nango_connections_bulk_update with the array of IDs, injecting the new webhook_version metadata flag across the entire customer base without overwriting their existing metadata.

Result: The code is deployed, and the entire fleet of Slack connections is tagged for the new webhook version logic in a matter of seconds.

Security and Access Control

Exposing an infrastructure control plane like Nango to an LLM requires strict governance. Truto's MCP tokens provide granular security controls to ensure Claude only does exactly what you permit.

  • Method Filtering: Limit the server to safe operations. By configuring methods: ["read"], you ensure the LLM can list connections and query records, but cannot trigger actions, start syncs, or deploy code.
  • Tag Filtering: Group tools by functional areas. You can restrict an MCP token to only expose tools tagged as proxy, preventing the AI from accessing core connection management or deployment tools.
  • Expiration (Time-to-Live): Set an expires_at datetime on the MCP token. This is perfect for giving an external consultant or a temporary AI agent scoped access to Nango for exactly 24 hours, after which the token self-destructs.
  • API Token Enforcement: Enable require_api_token_auth to force a two-layer security model. The client must possess the unique MCP server URL and pass a valid Truto API token in the Authorization header to execute any tool.

Strategic Wrap-Up

Managing integrations programmatically is difficult enough without forcing your engineering team to build custom AI tooling. By connecting Nango to Claude via a managed MCP server, you instantly grant your AI agents the ability to audit connections, deploy code, trigger syncs, and execute proxy requests securely.

Truto handles the dynamic tool generation, token management, and JSON-RPC protocol translation, allowing you to focus on building robust integration workflows rather than maintaining infrastructure plumbing.

More from our Blog