MCP Configuration¶

When a connector has MCP (Model Context Protocol) configuration enabled, the platform automatically generates an MCP server that exposes connector operations as tools for AI agents. This is how connectors become callable capabilities in agent workflows -- without writing any glue code.

How It Works¶

graph LR
    CD["Connector Descriptor<br/>(operations)"] --> Gen["MCP Server Generator"]
    Gen --> MCPS["FastMCP Server<br/>(auto-generated)"]
    MCPS --> Tools["MCP Tools<br/>(one per mapped operation)"]
    Tools --> Agent["Agent Runtime"]

    CI["Connector Instance<br/>(credentials)"] --> MCPS

    Agent --> |"calls tool"| MCPS
    MCPS --> |"executes operation"| API["External API"]

The flow:

The connector descriptor defines operations (API endpoints, parameters, auth)
The MCP configuration maps operations to tool names and descriptions
The platform generates an OpenAPI spec from the descriptor
A FastMCP server is created from the OpenAPI spec
Agents call the MCP tools, which route through the connector's execution pipeline
Credentials are injected at runtime based on the agent's scope

Enabling MCP¶

Add an mcp_config section to your connector descriptor:

mcp_config:
  enabled: true
  server_name: "jira_api"
  server_description: "Jira Cloud API tools for issue management"
  route_mappings:
    - operation_id: list_issues
      mcp_tool_name: search_jira_issues
      mcp_tool_description: "Search for Jira issues using JQL query language"
      parameter_mappings: {}

    - operation_id: create_issue
      mcp_tool_name: create_jira_issue
      mcp_tool_description: "Create a new issue in a Jira project"
      parameter_mappings:
        project_key: project
        issue_type: type

    - operation_id: get_issue
      mcp_tool_name: get_jira_issue
      mcp_tool_description: "Get details of a specific Jira issue by key"
      parameter_mappings:
        issue_key: key

    - operation_id: update_issue
      mcp_tool_name: update_jira_issue
      mcp_tool_description: "Update fields on an existing Jira issue"
      parameter_mappings: {}

Configuration Fields¶

Field	Required	Description
`enabled`	No	Whether MCP generation is active. Defaults to `false`
`server_name`	Yes	Identifier for the MCP server (1-100 chars)
`server_description`	Yes	Human-readable description (1-500 chars)
`route_mappings`	No	List of operation-to-tool mappings. Defaults to empty list

Route Mappings¶

Each route mapping connects a connector operation to an MCP tool:

Field	Required	Description
`operation_id`	Yes	Must match an `operation_id` in the connector's `operations` list
`mcp_tool_name`	Yes	The tool name agents will see and call (1-100 chars)
`mcp_tool_description`	Yes	Description shown to the model for tool selection (1-500 chars)
`parameter_mappings`	No	Rename parameters for the MCP interface

Parameter Mappings¶

Parameter mappings let you rename connector parameters to more agent-friendly names:

parameter_mappings:
  project_key: project      # connector param "project_key" → MCP param "project"
  issue_type: type           # connector param "issue_type" → MCP param "type"
  maxResults: limit          # connector param "maxResults" → MCP param "limit"

If parameter_mappings is empty, the original parameter names from the operation are used.

Write good tool descriptions

The mcp_tool_description is what the language model reads to decide when to use a tool. Be specific: instead of "Get data" write "Search for Jira issues using JQL query language. Returns issue keys, summaries, statuses, and assignees."

Selective Operation Exposure¶

You do not need to map every operation. Only operations listed in route_mappings become MCP tools. This lets you expose a curated subset of the connector's capabilities to agents.

Common patterns:

Read-only tools -- Map only GET operations for agents that should not modify data
Safe subset -- Exclude delete or admin operations from agent access
Task-specific -- Map only the operations relevant to a particular agent's purpose

# Only expose read operations as tools
route_mappings:
  - operation_id: list_issues
    mcp_tool_name: search_issues
    mcp_tool_description: "Search for issues matching criteria"
  - operation_id: get_issue
    mcp_tool_name: get_issue_details
    mcp_tool_description: "Get full details of a specific issue"
  # create_issue and delete_issue are NOT mapped — agents cannot use them

Server Caching¶

The platform caches generated MCP servers per connector instance. The cache key is derived from the connector instance ID, organization ID, and workspace ID.

The cache is automatically invalidated when:

Connector instance credentials are updated
Connector descriptor operations change
Connector instance is deleted

Per-request authentication

When an agent call includes a user-specific auth token, the MCP server is created fresh for that request (bypassing the cache) to ensure proper credential scoping.

Validation Rules¶

The platform validates MCP configuration when you register or update a connector:

Every operation_id in route_mappings must exist in the connector's operations list
MCP tool names must be unique across all route mappings
server_name must be provided when enabled is true

Validation errors prevent the connector from being saved.

Full Example¶

Here is a complete connector descriptor with MCP enabled for a ticket management system:

metadata:
  name: "Ticket System"
  slug: "ticket-system"
  version: "1.0.0"
  description: "Integration with internal ticket management system"
  publisher: "Platform Team"
  categories: [saas]

authentication:
  - type: api_key
    fields:
      - key: api_key
        label: "API Key"
        field_type: secret
        required: true
        secret: true
    test_endpoint:
      url: "https://tickets.internal.com/api/v1/me"
      method: GET
      expected_status: 200

operations:
  - operation_id: search_tickets
    endpoint: "https://tickets.internal.com/api/v1/tickets"
    method: GET
    summary: "Search tickets with filters"
    auth_type_ref: api_key
    auth_headers:
      X-API-Key: "{api_key}"
    parameters:
      - name: status
        location: query
        field_type: string
        description: "Filter by status (open, closed, in_progress)"
      - name: assignee
        location: query
        field_type: string
        description: "Filter by assignee email"
      - name: limit
        location: query
        field_type: integer
        default_value: 25

  - operation_id: get_ticket
    endpoint: "https://tickets.internal.com/api/v1/tickets/{ticket_id}"
    method: GET
    summary: "Get ticket by ID"
    auth_type_ref: api_key
    auth_headers:
      X-API-Key: "{api_key}"
    parameters:
      - name: ticket_id
        location: path
        field_type: string
        required: true

  - operation_id: create_ticket
    endpoint: "https://tickets.internal.com/api/v1/tickets"
    method: POST
    summary: "Create a new ticket"
    auth_type_ref: api_key
    auth_headers:
      X-API-Key: "{api_key}"
    parameters:
      - name: title
        location: body
        field_type: string
        required: true
      - name: description
        location: body
        field_type: string
      - name: priority
        location: body
        field_type: string
        default_value: "medium"

capabilities:
  sync_modes: [full_refresh]
  supports_schema_discovery: false

rate_limits:
  - scope: per_account
    limit: 1000
    interval_seconds: 60

sla:
  availability_percentage: 99.5
  latency_ms_p95: 1500

mcp_config:
  enabled: true
  server_name: "ticket_system"
  server_description: "Internal ticket management tools"
  route_mappings:
    - operation_id: search_tickets
      mcp_tool_name: search_tickets
      mcp_tool_description: "Search support tickets by status, assignee, or other filters. Returns ticket IDs, titles, statuses, and assignees."
    - operation_id: get_ticket
      mcp_tool_name: get_ticket
      mcp_tool_description: "Get full details of a support ticket including description, comments, and history."
    - operation_id: create_ticket
      mcp_tool_name: create_ticket
      mcp_tool_description: "Create a new support ticket with title, description, and priority."

When an agent is configured with a connector instance using this descriptor, it gets three tools: search_tickets, get_ticket, and create_ticket. The agent can reason about which tool to use based on the descriptions, and the platform handles credential injection, rate limiting, and request routing transparently.