Skip to main content

​
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: 
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

ParameterTypeRequiredDescription
server_urlstrYesURL of the MCP server
tool_namestrYesName of the tool to execute
tool_argsstrYesJSON template for tool arguments
transport_typestrNoTransport protocol (default: "http")
connection_timeoutintNoConnection timeout in seconds (default: 30)
server_namestrNoOptional server identifier
auth_headersDictNoAuthentication headers

​
Dynamic Tool Arguments

Use $variable syntax in tool_args to inject runtime values: 
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: 
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

config:
  auth_headers:
    Authorization: "Bearer ${API_TOKEN}"

​
API Key

config:
  auth_headers:
    X-API-Key: "${API_KEY}"

​
Custom Headers

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

OutputTypeDescription
mcp_resultDict[str, Any]The result returned by the MCP tool

​
Example: Multi-System Integration

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