MCP Tools - Kortix

Overview

MCP (Model Context Protocol) tools allow agents to connect to external services through standardized protocols. Kortix supports multiple MCP server types:

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

Discover available tools from a custom MCP server for a specific agent.

Authentication

Requires JWT authentication via the Authorization header.

Path Parameters

string

required

The unique identifier of the agent

Headers

string

required

The URL of the MCP server (for HTTP/SSE) or Composio profile ID

string

default:"sse"

The MCP server type: http, sse, or composio

string

Optional JSON string of custom headers for the MCP server

Response

array

Array of discovered tools from the MCP server

Show Tool Object

string

Tool name (e.g., GMAIL_SEND_EMAIL)

string

Tool description from the MCP server

boolean

Whether this tool is currently enabled for the agent

boolean

Whether this MCP server is already configured for the agent

string

The type of MCP server (http, sse, composio)

string

The MCP server URL or identifier

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"

import { KortixClient } from '@kortix/client';

const client = new KortixClient({
  apiKey: 'YOUR_API_KEY'
});

const tools = await client.agents.tools.discoverMcp('agt_abc123', {
  url: 'https://mcp.example.com',
  type: 'http'
});

console.log('Available tools:', tools.tools);

from kortix import KortixClient

client = KortixClient(api_key="YOUR_API_KEY")

tools = client.agents.tools.discover_mcp(
    "agt_abc123",
    url="https://mcp.example.com",
    type="http"
)

print(f"Available tools: {tools['tools']}")

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

Enable or disable specific tools from a custom MCP server.

Authentication

Requires JWT authentication.

Path Parameters

string

required

The unique identifier of the agent

Request Body

string

required

The MCP server URL or Composio profile ID

string

default:"sse"

The MCP server type: http, sse, or composio

array

required

Array of tool names to enable

Response

boolean

Whether the operation succeeded

array

Array of tool names that are now enabled

integer

Total number of enabled tools

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"]
  }'

const result = await client.agents.tools.updateMcpTools('agt_abc123', {
  url: 'https://mcp.example.com',
  type: 'http',
  enabled_tools: ['search_database', 'create_order']
});

console.log('Enabled tools:', result.enabled_tools);

result = client.agents.tools.update_mcp_tools(
    "agt_abc123",
    url="https://mcp.example.com",
    type="http",
    enabled_tools=["search_database", "create_order"]
)

print(f"Enabled {result['total_tools']} tools")

Example Response

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

Update Agent Custom MCPs

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

Update the complete list of custom MCP configurations for an agent.

Authentication

Requires JWT authentication.

Path Parameters

string

required

The unique identifier of the agent

Request Body

array

required

Array of MCP configuration objects

Show MCP Configuration Object

string

required

Display name for the MCP integration

string

required

MCP type: http, sse, composio, or json

string

Custom type identifier (for non-Composio MCPs)

object

required

Configuration object (varies by type)

Show HTTP/SSE Config

string

required

MCP server URL

object

Optional custom headers

Show Composio Config

string

required

Composio profile identifier

Show JSON/stdio Config

string

required

Command to execute

array

Command arguments

object

Environment variables

array

required

Array of tool names to enable from this MCP server

Response

boolean

Whether the operation succeeded

object

array

The updated list of MCP configurations

integer

Total number of enabled tools across all MCPs

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"]
      }
    ]
  }'

const result = await client.agents.tools.updateCustomMcps('agt_abc123', {
  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']
    }
  ]
});

result = client.agents.tools.update_custom_mcps(
    "agt_abc123",
    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

HTTP-based MCP servers use streamable HTTP for communication:

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

SSE MCP Servers

Server-Sent Events based MCP servers:

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

Composio Integrations

Pre-built integrations via Composio:

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

JSON/stdio MCP Servers

Local MCP servers via stdin/stdout:

{
  "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

error

MCP integrations not enabled

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

error

Worker not found

{
  "detail": "Worker not found"
}

error

Invalid request (missing URL, invalid config, etc.)

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

error

Custom worker limit exceeded

{
  "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"
  }
}

error

Internal server error

{
  "detail": "Internal server error"
}

MCP Tool Execution

MCP tools are executed using ephemeral connections:

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

This architecture prevents connection leaks and ensures tools always use fresh credentials.

Schema Caching

MCP tool schemas are cached for performance:

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

In production environments, private/local URLs are blocked:

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)

Local development environments bypass these restrictions.

Authentication

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

Best Practices

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

Rate Limits

MCP tool endpoints respect the following 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

​Overview

​Get Agent Custom MCP Tools

​Authentication

​Path Parameters

​Headers

​Response

​Example Request

​Example Response

​Update Agent Custom MCP Tools

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Update Agent Custom MCPs

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​MCP Server Types

​HTTP MCP Servers

​SSE MCP Servers

​Composio Integrations

​JSON/stdio MCP Servers

​Error Responses

​MCP Tool Execution

​Schema Caching

​Security Considerations

​URL Validation

​Authentication

​Best Practices

​Rate Limits

Overview

Get Agent Custom MCP Tools

Authentication

Path Parameters

Headers

Response

Example Request

Example Response

Update Agent Custom MCP Tools

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response

Update Agent Custom MCPs

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response

MCP Server Types

HTTP MCP Servers

SSE MCP Servers

Composio Integrations

JSON/stdio MCP Servers

Error Responses

MCP Tool Execution

Schema Caching

Security Considerations

URL Validation

Authentication

Best Practices

Rate Limits