MCP Integration

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 and Connic connects to the servers and makes their tools available at runtime. All MCP tool calls are traced and visible in run details.

Basic Usage

version: "1.0"

name: docs-assistant
type: llm
model: gemini/gemini-2.5-pro
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.

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. The agent runtime will tunnel the MCP connection through that bridge instead of calling the URL directly.

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.

The MCP server's host:port must be in the bridge agent's ALLOWED_HOSTS, the same allow-list used for connectors and custom-tool tunnels.

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, the framework 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: gemini/gemini-2.5-pro
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