MCP Servers

Connect your agents to external MCP servers to extend their capabilities with additional tools.

MCP servers expose tools that your agents can use alongside local tools. Configure them in your agent YAML. All MCP tool calls are traced and visible in run details. Compare the MCP server, connector, and client roles before choosing which side to configure.

Basic Usage

version: "1.0"

name: docs-assistant
type: llm
model: connic/kimi-k2.7-code-fast
description: "An assistant with access to library documentation via MCP"
system_prompt: |
  You are a helpful coding assistant with access to up-to-date
  library documentation through MCP tools.

# Connect to an MCP server
mcp_servers:
  - name: context7
    url: https://mcp.context7.com/mcp

Configuration Reference

mcp_servers:
  - name: github
    url: https://mcp.example.com/github
    headers:
      Authorization: "Bearer ${GITHUB_TOKEN}"
      X-User-Id: "${context.user_id}"

Use ${VAR_NAME} syntax for secrets. Configure variables in Settings → Variables. Connic forwards these static headers to the server; automatic MCP OAuth discovery and interactive authorization are not supported.

mcp_servers:
  - name: filesystem
    url: https://mcp.example.com/filesystem
    # Only allow specific tools
    tools:
      - read_file
      - list_directory

Restrict which tools are available. Useful for limiting agents to read-only operations or preventing use of dangerous tools.

Multiple Servers

mcp_servers:
  - name: docs
    url: https://mcp.context7.com/mcp

  - name: search
    url: https://mcp.example.com/search
    headers:
      X-API-Key: "${SEARCH_API_KEY}"

  - name: database
    url: https://mcp.internal.company.com/db
    headers:
      Authorization: "Bearer ${DB_TOKEN}"
    tools:
      - query
      - list_tables

Connect to multiple MCP servers at once. Each server's tools become available to the agent.

When your MCP server runs inside a private network (VPC, on-prem, behind a corporate firewall) and is not reachable from the public internet, set the bridge field to a Connic Bridge ID. Connic routes the MCP connection through that bridge.

mcp_servers:
  - name: internal-mcp
    url: http://mcp.internal:8080/mcp
    bridge: ${INTERNAL_BRIDGE_ID}

The url is the address the bridge sees from inside your network. Typically a hostname that only resolves there (for example mcp.internal:8080). The bridge ID is copied from Project Settings > Bridge. Both the URL and the bridge ID support ${VAR} substitution, so you can keep them out of YAML and store them as variables.

If the bridge agent has ALLOWED_HOSTS configured, it must include the MCP server's host:port. Unset or empty allows every target reachable from the bridge's network.

Discoverable MCP Servers

Some MCP servers expose a large number of tools. Loading all of them into the LLM context increases token usage and can reduce accuracy. Setting discoverable: true keeps the server's tools out of the LLM context and instead indexes them for on-demand search.

When an MCP server is marked as discoverable, Connic indexes its tools and lets the agent find and call them on demand with a natural-language query. Only the tools that match the query are loaded, keeping the LLM context lean.

version: "1.0"

name: research-agent
type: llm
model: connic/gpt-5.6-sol
description: "Agent with a large MCP toolset available on demand"
system_prompt: |
  You have access to many research tools. When you need one,
  search for it by describing what you need.

mcp_servers:
  - name: research-hub
    url: https://mcp.example.com/research
    discoverable: true   # all tools indexed for search, not loaded upfront
    headers:
      Authorization: "Bearer ${RESEARCH_TOKEN}"

Error Handling