MCP Servers

External MCP servers provide additional agent tools, with configuration for Streamable HTTP, authentication headers, tool filtering, discovery, and bridge routing.

MCP servers expose tools that agents can use alongside local tools. Configure them in the 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. For servers that require each end user to sign in with their own account, use per-user sign-in.

Per-User Sign-In

Some MCP servers act for one person and accept only that person's OAuth token, with no shared API key. An OAuth app holds the provider settings for an environment. Each end user signs in once, connic stores their tokens, and every run for that user sends their current access token to the server.

1. Register an OAuth client with the provider and use the redirect URL shown in Settings → OAuth Apps.
2. Add the OAuth app there with its authorization URL, token URL, client ID, client secret, scopes, and the return URLs of your application. If the token URL is only reachable inside your network, select a Bridge.
3. Reference the app from the MCP server and name the context path that identifies the end user. Set that path in middleware after verifying the user.

mcp_servers:
  - name: sisense
    url: https://bi.example.com/mcp
    oauth:
      app: sisense            # OAuth app in Settings → OAuth Apps
      user: context.user_id   # set by middleware for every run
      connect_tool: true      # adds connect_sisense for conversational agents

Connecting Users

From your application: create a sign-in link with the REST API, for example behind a Connect button in your settings page. Use the same user ID that your middleware sets. The user signs in with the provider and returns to return_url with connic_oauth=connected, denied, or failed in the query. The same API lists connected users and disconnects them.

curl -X POST "https://api.connic.co/v1/projects/{project_id}/oauth-apps/{app_id}/connect-links" \
  -H "Authorization: Bearer cnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "emp_42", "return_url": "https://app.example.com/settings/integrations"}'

# {"url": "https://api.connic.co/v1/oauth/start/...", "expires_at": "2026-10-12T10:10:00Z"}

From a conversation: with connect_tool: true, a user without a token gets a connect_<server name> tool instead of the server's tools. The agent shares the link it returns, and after signing in the user's next message can use the server. Voice agents do not expose this tool. Leave it off for agents that run without a person to click the link; they use tokens of users who already signed in.

At Run Time

• A run without a value at the user path, or for a user who has not signed in, leaves the server out.
• Tokens that expire within five minutes are refreshed first when the provider issued a refresh token.
• When the server answers 401, connic refreshes the token once and retries. Without a refresh token, the stored token is deleted and the user signs in again.
• Sign-in links work once and expire after 10 minutes.
• Deploying fails when a referenced OAuth app does not exist in the environment.
• connic does not discover authorization servers or register clients automatically. Register the client with the provider first.

Conditional and Optional Servers

Per-user credentials often exist for only some users. Set condition to connect a server only when an expression is true. It is evaluated at the start of every run, after middleware, with the same grammar as conditional tools. When it is false or references a missing key, the server and its tools are left out of that run and its ${context.*} headers are not resolved.

mcp_servers:
  - name: analytics
    url: https://analytics.example.com/mcp
    headers:
      Authorization: "Bearer ${context.analytics_token}"
    condition: context.analytics_token != null
    optional: true

tools:
  - analytics.get_connect_link: context.analytics_token == null

Set optional: true to keep the run going when connecting to the server or listing its tools fails, for example with a 401 after a stored token was revoked. Without it, that failure fails the run.

connic records MCP failures in context["mcp_errors"], keyed by server name. stage is discovery or call, and status is 401 when the server rejected the credentials. Read it in the after middleware hook to remove a revoked credential, so the next run offers the reconnect path.

async def after(response, context):
    if context.get("mcp_errors", {}).get("analytics", {}).get("status") == 401:
        await delete_analytics_token(context["user_id"])
    return response

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 an 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 the private network. Typically, this is a hostname that only resolves there (for example mcp.internal:8080). Copy the bridge ID from Project Settings > Bridge. Both the URL and the bridge ID support ${VAR} substitution, so they can remain outside YAML 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