name: connect-to-nango-mcp
description: Connect agents to external platforms (HubSpot, Salesforce, etc.) via Nango using header authentication.
version: 8.0.0
author: agent-skills-workbench
mcp-servers: ["nango"]
tags: [nango, mcp, integration, hubspot, salesforce, portable]

Nango MCP Integration Skill

This skill enables agents to connect to third-party SaaS platforms (HubSpot, Salesforce, etc.) through Nango's proxy and MCP server.

MCP Server Requirements

This skill requires the Nango MCP server.

Connection Details:
- URL: https://api.nango.dev/mcp
- Transport: HTTP

Authentication:
The Nango MCP server uses header-based authentication at connection time.

Required Headers:
- Authorization: Bearer <NANGO_SECRET_KEY>
- connection-id: <connectionId from Step 3>
- provider-config-key: <provider name>

Available Tools (vary by provider):
- HubSpot: whoami, list_contacts, create_contact, query
- Salesforce: query, create_record, whoami

Prerequisites

Credentials

• NANGO_SECRET_KEY: Your Nango secret key from nango.dev.
• NANGO_DEFAULT_USER_ID: The end-user identifier for the connection.

Runtime

• Node.js 18+ (for bundled scripts using built-in fetch)

Workflow

Phase 1: Check Connection Status

First, determine if the Nango MCP server is already connected. If Nango-specific tools (like whoami or list_contacts) are already available in your environment, you can skip to normal usage.

Phase 2: Handle Authentication

If tools are not available, you must obtain a connectionId.

1. Identify Provider: Determine which provider the user wants to connect to (e.g., hubspot, salesforce) by checking the original request or current skill context. Only ask the user if the provider is not mentioned and cannot be inferred.
2. Get Secret Key: Attempt to retrieve the NANGO_SECRET_KEY from the environment variables (e.g., via platform tools or direct environment access). Do NOT ask the user for this key if it is already available.
3. Run the authentication script: Execute scripts/check-auth.js passing the inferred provider and the retrieved secret key.
   bash node scripts/check-auth.js <provider> <secret_key>
4. Handle Response:
5. Success: The script returns a connectionId. Proceed immediately to configure the MCP server.
6. Needs Auth: The script returns an authUrl. Present this URL to the user and wait for them to confirm completion. Once confirmed, re-run the script to get the connectionId.
7. Error: Report the error to the user.

Phase 3: Configure and Use MCP Server

Once you have the connectionId, IMMEDIATELY PROCEED with the following steps without pausing:

Step 3.1 - Provision Authentication Headers:
Configure the Nango MCP server with these three required headers (use your platform's credential storage mechanism):
- Server identifier: nango-mcp-server (or similar)
- Server URL: https://api.nango.dev/mcp
- Headers to configure (provision all three):
1. Authorization: Bearer <NANGO_SECRET_KEY>
2. connection-id: <connectionId> (from Phase 2)
3. provider-config-key: <provider> (e.g., "hubspot", "salesforce")

Platform-specific notes:
- Some platforms may require separate calls to provision each header
- Others may accept all headers in a single configuration call
- Use whatever credential/header provisioning tool your platform provides

Step 3.2 - Connect to MCP Server:
Establish connection to the Nango MCP server. The server will validate your headers and return available tools based on the provider.

Step 3.3 - List Available Tools:
Query the MCP server to discover which tools are now available (e.g., whoami, list_contacts, query, etc.). This confirms authentication succeeded.

Step 3.4 - Execute User's Request:
Use the appropriate tool(s) to fulfill the user's original request immediately.

[CRITICAL - DO NOT STOP]:
- Execute steps 3.1 through 3.4 in sequence without pausing
- Do NOT ask for permission between steps
- Do NOT report "I've configured the headers" and stop
- The user should see the final result (e.g., the HubSpot data), not intermediate status messages
- If authentication fails, report the error with details

Bundled Scripts

scripts/check-auth.js

Checks Nango authentication status and initiates the authentication flow if needed.

Usage:
node check-auth.js <provider> <secret_key>

Output: JSON with status (success, needs_auth, error) and relevant data.

scripts/config-helper.js

Utility to help generate configuration snippets for various agent platforms.

Troubleshooting

• Authentication failed: Verify the NANGO_SECRET_KEY and ensure the provider is configured in your Nango account.
• Tools not appearing: Ensure the headers are correctly sent during the MCP connection handshake.
• Connection-id not found: The user may need to complete the authentication flow via the provided authUrl.