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

agent_id

string

required

The unique identifier of the agent

Headers

X-MCP-URL

string

required

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

X-MCP-Type

string

default:"sse"

The MCP server type: http, sse, or composio

X-MCP-Headers

string

Optional JSON string of custom headers for the MCP server

Response

tools

array

Array of discovered tools from the MCP server

Show Tool Object

name

string

Tool name (e.g., GMAIL_SEND_EMAIL)

description

string

Tool description from the MCP server

enabled

boolean

Whether this tool is currently enabled for the agent

has_mcp_config

boolean

Whether this MCP server is already configured for the agent

server_type

string

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

server_url

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"

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

agent_id

string

required

The unique identifier of the agent

Request Body

url

string

required

The MCP server URL or Composio profile ID

type

string

default:"sse"

The MCP server type: http, sse, or composio

enabled_tools

array

required

Array of tool names to enable

Response

success

boolean

Whether the operation succeeded

enabled_tools

array

Array of tool names that are now enabled

total_tools

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

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

agent_id

string

required

The unique identifier of the agent

Request Body

custom_mcps

array

required

Array of MCP configuration objects

Show MCP Configuration Object

name

string

required

Display name for the MCP integration

type

string

required

MCP type: http, sse, composio, or json

customType

string

Custom type identifier (for non-Composio MCPs)

config

object

required

Configuration object (varies by type)

Show HTTP/SSE Config

url

string

required

MCP server URL

headers

object

Optional custom headers

Show Composio Config

profile_id

string

required

Composio profile identifier

Show JSON/stdio Config

command

string

required

Command to execute

args

array

Command arguments

env

object

Environment variables

enabledTools

array

required

Array of tool names to enable from this MCP server

Response

success

boolean

Whether the operation succeeded

data

object

custom_mcps

array

The updated list of MCP configurations

total_enabled_tools

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

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

403

error

MCP integrations not enabled

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

404

error

Worker not found

{
  "detail": "Worker not found"
}

400

error

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

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

402

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

500

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

Getting Started

Agents

Threads

Tools

SDK

Documentation Index

​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