> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect to Model Context Protocol servers in Agent Composer

## Description

Agent Composer supports the Model Context Protocol (MCP), allowing your agents to execute tools on external MCP servers. This enables integration with CRM systems, databases, APIs, and other enterprise services.

## MCPClientStep

Use `MCPClientStep` to execute tools on MCP servers:

```yaml theme={null}
mcp_call:
  type: MCPClientStep
  config:
    server_url: "https://mcp-server.example.com"
    tool_name: "search_accounts"
    tool_args: '{"query": "$query"}'
    auth_headers:
      Authorization: "Bearer ${API_TOKEN}"
  input_mapping:
    query: __inputs__#query
```

## Configuration Parameters

| Parameter            | Type   | Required | Description                                   |
| -------------------- | ------ | -------- | --------------------------------------------- |
| `server_url`         | `str`  | Yes      | URL of the MCP server                         |
| `tool_name`          | `str`  | Yes      | Name of the tool to execute                   |
| `tool_args`          | `str`  | Yes      | JSON template for tool arguments              |
| `transport_type`     | `str`  | No       | Transport protocol (default: `"http"`)        |
| `connection_timeout` | `int`  | No       | Connection timeout in seconds (default: `30`) |
| `server_name`        | `str`  | No       | Optional server identifier                    |
| `auth_headers`       | `Dict` | No       | Authentication headers                        |

## Dynamic Tool Arguments

Use `$variable` syntax in `tool_args` to inject runtime values:

```yaml theme={null}
mcp_call:
  type: MCPClientStep
  config:
    server_url: "https://crm.example.com/mcp"
    tool_name: "get_customer"
    tool_args: '{"customer_id": "$customer_id", "include_history": true}'
  input_mapping:
    customer_id: extract_id#customer_id
```

## Using MCP as an Agentic Tool

Configure MCP as a tool for `AgenticResearchStep`:

```yaml theme={null}
research:
  type: AgenticResearchStep
  config:
    tools_config:
      - name: search_crm
        description: |
          Search customer records in the CRM system.
          Returns customer details, order history, and support tickets.
        step_config:
          type: MCPClientStep
          config:
            server_url: "https://crm.example.com/mcp"
            tool_name: "search_customers"
            tool_args: '{"query": "$query"}'
            auth_headers:
              Authorization: "Bearer ${CRM_API_TOKEN}"

      - name: search_docs
        description: Search internal documentation.
        step_config:
          type: SearchUnstructuredDataStep
          config:
            top_k: 50

    agent_config:
      agent_loop:
        num_turns: 10
        model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
        research_guidelines_prompt: |
          You have access to:
          - `search_crm` — Look up customer information
          - `search_docs` — Search documentation

  input_mapping:
    message_history: create_message_history#message_history
```

## Authentication

### Bearer Token

```yaml theme={null}
config:
  auth_headers:
    Authorization: "Bearer ${API_TOKEN}"
```

### API Key

```yaml theme={null}
config:
  auth_headers:
    X-API-Key: "${API_KEY}"
```

### Custom Headers

```yaml theme={null}
config:
  auth_headers:
    Authorization: "Bearer ${TOKEN}"
    X-Tenant-ID: "${TENANT_ID}"
    X-Request-Source: "contextual-agent"
```

## Secret Handling

Secrets (API keys, tokens) are automatically encrypted when saved. After encryption, secrets are replaced with unique IDs (e.g., `CTXL_AGENT_SECRET_ohs3gpu6llyt`). To update a secret, replace the secret ID with the new value and save.

## Outputs

| Output       | Type             | Description                         |
| ------------ | ---------------- | ----------------------------------- |
| `mcp_result` | `Dict[str, Any]` | The result returned by the MCP tool |

## Example: Multi-System Integration

```yaml theme={null}
nodes:
  # Get customer from CRM
  get_customer:
    type: MCPClientStep
    config:
      server_url: "https://crm.example.com/mcp"
      tool_name: "get_customer"
      tool_args: '{"email": "$email"}'
      auth_headers:
        Authorization: "Bearer ${CRM_TOKEN}"
    input_mapping:
      email: extract_email#email

  # Get orders from order system
  get_orders:
    type: MCPClientStep
    config:
      server_url: "https://orders.example.com/mcp"
      tool_name: "get_orders"
      tool_args: '{"customer_id": "$customer_id"}'
      auth_headers:
        Authorization: "Bearer ${ORDERS_TOKEN}"
    input_mapping:
      customer_id: get_customer#mcp_result

  # Generate response with all context
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      customer_info: get_customer#mcp_result
      order_history: get_orders#mcp_result
```

## Related

* [Webhooks](/reference/ac-webhooks)
* [Tools Configuration](/reference/ac-tools-config)
* [Agentic Workflows](/reference/ac-agentic-workflows)