Connic Composer SDK

MCP Integration

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

What is MCP?

Extend your agents with external tools via the Model Context Protocol

MCP servers expose tools that your agents can use alongside local tools. Configure them in your agent YAML and Connic automatically connects to the servers and makes their tools available at runtime. All MCP tool calls are traced and visible in run details.

How MCP Works in Connic

Add mcp_servers to your agent YAML. At runtime, Connic connects to each server, discovers available tools, and exposes them to your LLM agent. The agent can call MCP tools just like local tools. Connic handles the communication.

Basic Usage

yaml

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

Field	Type	Status	Description
name	string	Required	Identifier for the MCP server. Used in logs and traces.
url	string	Required	The URL of the MCP server endpoint. Supports ${VAR} syntax for environment variables.
tools	string[]	Optional	List of specific tools to use from this server. If omitted, all tools are available.
headers	object	Optional	HTTP headers to send with requests. Use for authentication. Supports ${VAR} syntax.

Authentication

yaml

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

Use ${VAR_NAME} syntax for secrets. Configure variables in Settings → Variables.

Tool Filtering

yaml

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

yaml

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 simultaneously. Each server's tools become available to the agent.

Error Handling

Connection Failures: If an MCP server is unavailable at startup, the agent continues running without that server's tools.

Tool Failures: Errors are captured in traces and returned to the LLM for handling.

Retry Options: Use the agent's standardretry_options to automatically retry failed runs.

Security

Never hardcode API keys or tokens in YAML files. Always use environment variables with the ${VAR_NAME} syntax.

Limitations

Only HTTP/SSE transport is supported (not stdio)
MCP servers must be network-accessible from the agent container
Only LLM agents support MCP (not Tool or Sequential agents)

Write Custom Tools

Create your own tools in Python

Agent Configuration

Configure agents with MCP servers

Environment Variables

Store MCP credentials securely

Predefined Tools

Built-in tools without external servers