MCP (Model Context Protocol)

Overview

MCP (Model Context Protocol) allows Tool Agents to access tools from external MCP servers. Instead of relying only on built-in tools, agents can connect to external services that expose specialized capabilities — such as document management systems, databases, or third-party APIs.

How It Works

1. Register an MCP server with the platform
2. Configure a Tool Agent with an mcp tool type referencing the server
3. Invoke the agent — it discovers and uses the server's tools automatically

Registering an MCP Server

Register an external MCP server so agents can use its tools.

POST /v1/mcp-servers

{
    "name": "Document Manager",
    "description": "Manages documents in an external system",
    "url": "https://mcp.example.com/sse",
    "validationMode": "immediate",
    "auth": {
        "type": "apiKey",
        "config": {
            "header": "X-API-Key",
            "apiKeyValue": "your-api-key"
        }
    }
}

Required Fields

Parameter	Description	Required
name	Display name for the server	Yes
url	Server URL (HTTPS required in production)	Yes
description	Description of what the server provides	No
validationMode	skip, immediate, or async	No (default: immediate)
auth	Authentication configuration	Yes

Authentication Types

API Key

{
    "type": "apiKey",
    "config": {
        "header": "X-API-Key",
        "apiKeyValue": "your-secret-key"
    }
}

OIDC (OpenID Connect)

{
    "type": "oidc",
    "config": {
        "issuer": "https://auth.example.com",
        "clientId": "client-id",
        "clientSecret": "client-secret",
        "grantType": "client_credentials",
        "scopes": ["openid"],
        "audience": "https://api.example.com"
    }
}

info

Credentials are stored securely and never returned in API responses.

Validation Modes

Mode	Behavior
skip	No validation; server marked active immediately
immediate	Validates the MCP handshake before returning (default)
async	Validation runs in the background; server is initially inactive

Response

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Document Manager",
    "url": "https://mcp.example.com/sse",
    "status": "active",
    "validation": {
        "state": "valid"
    },
    "health": {
        "state": "healthy"
    },
    "origin": "user"
}

Managing MCP Servers

Method	Endpoint	Description
GET	/v1/mcp-servers	List all MCP servers
GET	/v1/mcp-servers/{server_id}	Get server details
PUT	/v1/mcp-servers/{server_id}	Update a server
DELETE	/v1/mcp-servers/{server_id}	Delete a server
POST	/v1/mcp-servers/{server_id}/validate	Trigger validation
GET	/v1/mcp-servers/{server_id}/tools	List available tools

Discovering Server Tools

Before configuring an agent, you can inspect which tools a server provides:

GET /v1/mcp-servers/{server_id}/tools

Using MCP in a Tool Agent

Add an mcp tool to your agent configuration, referencing a registered server by its ID:

{
    "name": "Document Assistant",
    "description": "Assistant that manages documents via MCP",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-sonnet-4-20250514-v1:0",
        "systemPrompt": "You are a helpful assistant with access to document management tools.",
        "tools": [
            {
                "toolType": "mcp",
                "name": "document_tools",
                "description": "Document management operations",
                "mcpServerReferences": [
                    {
                        "id": "550e8400-e29b-41d4-a716-446655440000",
                        "validationMode": "strict",
                        "toolConfiguration": {
                            "allowedTools": ["read_document", "search_documents"]
                        }
                    }
                ]
            }
        ]
    }
}

MCP Server Reference Fields

Field	Description	Required
id	UUID of a registered MCP server	Yes (or url)
url	Direct URL to an MCP server	Yes (or id)
validationMode	strict or lenient (controls tool-call validation at invocation time; distinct from the server-level validationMode used during registration)	No
toolConfiguration.allowedTools	Allowlist of tool names the agent can use	No (all tools if omitted)

tip

Use id references for production. Use url for quick prototyping or deployment workflows where servers aren't pre-registered.

Referencing Multiple Servers

An agent can connect to multiple MCP servers:

{
    "tools": [
        {
            "toolType": "mcp",
            "name": "external_tools",
            "description": "Tools from multiple servers",
            "mcpServerReferences": [
                {
                    "id": "server-uuid-1",
                    "toolConfiguration": {
                        "allowedTools": ["read_document"]
                    }
                },
                {
                    "id": "server-uuid-2",
                    "toolConfiguration": {
                        "allowedTools": ["query_database"]
                    }
                }
            ]
        }
    ]
}

Best Practices

1. Use allowedTools — restrict which tools an agent can access to prevent unintended actions
2. Use id references — reference registered servers by ID rather than URL for better security and manageability
3. Use HTTPS — required in production for secure communication
4. Set appropriate timeouts — long-running MCP tools may need higher timeout values in inferenceConfig
5. Validate first — use immediate validation to catch connectivity issues at registration time
6. Discover tools — use GET /v1/mcp-servers/{server_id}/tools to inspect available tools before configuring agents