MCP Tools

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kortix-ai/suna/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Composio: Pre-built integrations (Gmail, Slack, GitHub, etc.)
• Custom HTTP: Custom MCP servers over HTTP
• Custom SSE: Custom MCP servers using Server-Sent Events
• Custom JSON/stdio: Local MCP servers via stdin/stdout

​

Get Agent Custom MCP Tools

GET /agents/{agent_id}/custom-mcp-tools

​

Authentication

​

Path Parameters

​

Headers

​

Response

​

Example Request

curl -X GET "https://api.kortix.ai/agents/agt_abc123/custom-mcp-tools" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-MCP-URL: https://mcp.example.com" \
  -H "X-MCP-Type: http"

​

Example Response

{
  "tools": [
    {
      "name": "search_database",
      "description": "Search the product database",
      "enabled": false
    },
    {
      "name": "create_order",
      "description": "Create a new order",
      "enabled": true
    },
    {
      "name": "get_inventory",
      "description": "Get current inventory levels",
      "enabled": false
    }
  ],
  "has_mcp_config": true,
  "server_type": "http",
  "server_url": "https://mcp.example.com"
}

​

Update Agent Custom MCP Tools

POST /agents/{agent_id}/custom-mcp-tools

​

Authentication

​

Path Parameters

​

Request Body

​

Response

​

Example Request

curl -X POST "https://api.kortix.ai/agents/agt_abc123/custom-mcp-tools" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mcp.example.com",
    "type": "http",
    "enabled_tools": ["search_database", "create_order"]
  }'

​

Example Response

{
  "success": true,
  "enabled_tools": ["search_database", "create_order"],
  "total_tools": 2
}

​

Update Agent Custom MCPs

PUT /agents/{agent_id}/custom-mcp-tools

​

Authentication

​

Path Parameters

​

Request Body

​

Response

​

Example Request

curl -X PUT "https://api.kortix.ai/agents/agt_abc123/custom-mcp-tools" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_mcps": [
      {
        "name": "Custom HTTP MCP",
        "type": "http",
        "customType": "http",
        "config": {
          "url": "https://mcp.example.com"
        },
        "enabledTools": ["search_database", "create_order"]
      },
      {
        "name": "Gmail",
        "type": "composio",
        "config": {
          "profile_id": "prof_xyz789"
        },
        "enabledTools": ["GMAIL_SEND_EMAIL", "GMAIL_CREATE_DRAFT"]
      }
    ]
  }'

​

Example Response

{
  "success": true,
  "data": {
    "custom_mcps": [
      {
        "name": "Custom HTTP MCP",
        "type": "http",
        "customType": "http",
        "config": {
          "url": "https://mcp.example.com"
        },
        "enabledTools": ["search_database", "create_order"]
      },
      {
        "name": "Gmail",
        "type": "composio",
        "config": {
          "profile_id": "prof_xyz789"
        },
        "enabledTools": ["GMAIL_SEND_EMAIL", "GMAIL_CREATE_DRAFT"]
      }
    ],
    "total_enabled_tools": 4
  }
}

​

MCP Server Types

​

HTTP MCP Servers

{
  "name": "Custom HTTP MCP",
  "type": "http",
  "customType": "http",
  "config": {
    "url": "https://mcp.example.com",
    "headers": {
      "Authorization": "Bearer token123"
    }
  },
  "enabledTools": ["tool1", "tool2"]
}

​

SSE MCP Servers

{
  "name": "SSE MCP Server",
  "type": "sse",
  "customType": "sse",
  "config": {
    "url": "https://sse.example.com/events"
  },
  "enabledTools": ["realtime_data"]
}

​

Composio Integrations

{
  "name": "Gmail",
  "type": "composio",
  "config": {
    "profile_id": "prof_xyz789"
  },
  "enabledTools": [
    "GMAIL_SEND_EMAIL",
    "GMAIL_CREATE_DRAFT",
    "GMAIL_REPLY_TO_THREAD"
  ]
}

​

JSON/stdio MCP Servers

{
  "name": "Local Tool",
  "type": "json",
  "customType": "json",
  "config": {
    "command": "node",
    "args": ["/path/to/mcp-server.js"],
    "env": {
      "API_KEY": "key123"
    }
  },
  "enabledTools": ["local_action"]
}

​

Error Responses

{
  "detail": "MCP integrations are not enabled"
}

{
  "detail": "Worker not found"
}

{
  "detail": "MCP URL is required"
}

{
  "detail": {
    "message": "Maximum of 5 custom workers allowed for your current plan. You have 5 custom workers.",
    "current_count": 5,
    "limit": 5,
    "tier_name": "Pro",
    "error_code": "CUSTOM_WORKER_LIMIT_EXCEEDED"
  }
}

{
  "detail": "Internal server error"
}

​

MCP Tool Execution

1. Discovery: Tool schemas are cached in Redis (24-hour TTL)
2. Activation: Tools are activated on first use (JIT loading)
3. Execution: Each call creates a fresh connection to the MCP server
4. Result: Connection is closed immediately after execution

​

Schema Caching

• Cache Key: mcp_schema:{toolkit_slug}
• TTL: 24 hours
• Storage: Redis
• Invalidation: Automatic on TTL expiry or manual via registry methods

​

Security Considerations

​

URL Validation

• Localhost addresses (127.0.0.1, ::1)
• Private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Link-local addresses (169.254.0.0/16)

​

Authentication

• Composio: Authentication handled via profile configuration
• Custom MCPs: Use custom headers for API keys/tokens
• Private MCPs: Deploy behind authentication gateway

​

Best Practices

1. Test MCP servers: Use the discovery endpoint before enabling tools
2. Enable selectively: Only enable tools your agent needs
3. Monitor usage: Track which tools are being called
4. Update regularly: Keep MCP configurations in sync with server changes
5. Handle failures: MCP servers may be temporarily unavailable
6. Cache schemas: Let the system cache schemas for performance
7. Version agents: Use agent versions when changing MCP configurations

​

Rate Limits

• Discovery: Max 30 seconds timeout per server
• Execution: Max 30 seconds timeout per tool call
• Custom MCPs: Limited by subscription tier (check plan limits)
• Connection pool: Ephemeral connections prevent pool exhaustion