Nango API Integration for AI Agents#

Nango provides unified API access for AI agents with OAuth handling, 700+ pre-built integrations, and MCP server support. This skill helps you connect your agent to any external API.

Why Nango for Agents?#

• 700+ APIs pre-integrated - No need to build each integration from scratch
• 2800+ pre-built actions - Ready-to-use API operations
• MCP servers per app - Model Context Protocol support
• 1:1 API access - No abstraction layer, you see exact API requests
• White-label OAuth - Embeddable auth flows
• Any backend language - Works with Python, Node, etc.
• AI-generated code - Write integration logic with AI

Quick Start#

Step 1: Create Nango Account#

1. Go to https://nango.dev
2. Sign up for a free account
3. Create a new project
4. Get your API key from Settings

Step 2: Install Nango SDK#

bash

# Python
pip install nango

# Node.js
npm install @nangohq/node-client

Step 3: Configure Environment#

Add to your environment:

bash

NANGO_SECRET_KEY=your-secret-key-here
NANGO_HOST=https://api.nango.dev  # or self-hosted

Integration Patterns#

Pattern 1: OAuth Flow#

For APIs requiring OAuth (Google, Slack, GitHub, etc.):

python

from nango import Nango

nango = Nango()

# Get OAuth URL
auth_url = nango.get_auth_url(
    provider="google",
    redirect_uri="https://your-app.com/callback"
)

# User visits auth_url, authorizes, returns with code
# Exchange code for connection
connection = nango.create_connection(
    provider="google",
    code="auth_code_from_callback",
    connection_id="user-google-123"
)

# Now make API calls
result = nango.proxy(
    provider="google",
    endpoint="/gmail/v1/users/me/messages",
    connection_id="user-google-123"
)

Pattern 2: API Key#

For APIs using API keys (Stripe, OpenAI, etc.):

python

from nango import Nango

nango = Nango()

# Set API key for provider
nango.set_credentials(
    provider="stripe",
    connection_id="user-stripe-123",
    credentials={"api_key": "sk_test_xxx"}
)

# Make calls
customers = nango.proxy(
    provider="stripe",
    endpoint="/v1/customers",
    connection_id="user-stripe-123"
)

Pattern 3: MCP Server#

For Model Context Protocol integration:

python

# Get MCP server configuration for a provider
mcp_config = nango.get_mcp_server(
    provider="github",
    connection_id="user-github-123"
)

# Use with MCP-compatible agents
# The config includes tools, resources, and prompts

Popular API Integrations#

ProviderUse CaseAuth TypeGoogleGmail, Calendar, DriveOAuthSlackMessages, ChannelsOAuthGitHubRepos, Issues, PRsOAuthSalesforceCRM DataOAuthStripePaymentsAPI KeyNotionNotes, DatabasesOAuthLinearIssues, ProjectsOAuthHubSpotCRM, MarketingOAuth

Creating Custom Integrations#

Template for New Provider#

typescript

// integrations/my-custom-api.ts
import { NangoIntegration } from '@nangohq/types';

export default NangoIntegration({
  // Provider name
  provider: 'my-custom-api',

  // Authentication type
  auth: {
    type: 'api_key', // or 'oauth2', 'basic'
    credentials: {
      api_key: { type: 'string', required: true }
    }
  },

  // Available actions
  actions: {
    list_items: {
      endpoint: '/items',
      method: 'GET',
      output: { type: 'array' }
    },
    create_item: {
      endpoint: '/items',
      method: 'POST',
      input: { type: 'object' },
      output: { type: 'object' }
    }
  }
});

Deploy Custom Integration#

bash

# Deploy to Nango
nango deploy integrations/my-custom-api.ts

Error Handling#

python

from nango import Nango, NangoError

try:
    result = nango.proxy(
        provider="github",
        endpoint="/repos/owner/repo/issues",
        connection_id="user-github-123"
    )
except NangoError as e:
    if e.code == "auth_expired":
        # Re-authorize
        auth_url = nango.get_auth_url("github")
        print(f"Please re-authorize: {auth_url}")
    elif e.code == "rate_limited":
        # Wait and retry
        time.sleep(e.retry_after)
    else:
        raise

Best Practices for Agents#

1. Connection Management#

• Store connection IDs with user context
• Check connection health before operations
• Implement re-auth flows automatically

2. Error Recovery#

• Handle rate limits gracefully
• Cache frequently accessed data
• Provide clear error messages to users

3. Security#

• Never expose API keys in prompts
• Use environment variables for secrets
• Implement permission scoping

4. Performance#

• Batch operations when possible
• Use webhooks instead of polling
• Implement request caching

MCP Integration for OpenClaw#

To use Nango with OpenClaw agents:

python

# In your OpenClaw skill or tool
from nango import Nango

class NangoTool:
    def __init__(self):
        self.nango = Nango()

    def call_api(self, provider: str, endpoint: str, connection_id: str, **params):
        """Generic API calling tool for any provider."""
        return self.nango.proxy(
            provider=provider,
            endpoint=endpoint,
            connection_id=connection_id,
            params=params
        )

    def list_providers(self):
        """List all available providers."""
        return self.nango.list_providers()

    def get_provider_actions(self, provider: str):
        """Get available actions for a provider."""
        return self.nango.get_actions(provider)

Common Issues#

Issue: "Connection not found"#

• Ensure connection_id matches what was created
• Check if credentials expired

Issue: "Provider not supported"#

• Check full list at https://nango.dev/integrations
• Create custom integration for unsupported providers

Issue: "Rate limited"#

• Implement exponential backoff
• Consider upgrading Nango plan

Resources#

• Nango Dashboard: https://app.nango.dev
• Documentation: https://docs.nango.dev
• Integration Catalog: https://nango.dev/integrations
• GitHub: https://github.com/NangoHQ/nango
• Community: https://nango.dev/community

Pricing#

• Free Tier: 10,000 API calls/month
• Pro: $49/month for 100,000 calls
• Enterprise: Custom pricing for unlimited

Free tier is sufficient for development and small projects.