Connections

Connections give your AI agents access to external services and data at runtime. Configure a provider once, assign it to specific repos or agent types, and Optio automatically injects it into agent pods when tasks execute.

Under the hood, connections use the Model Context Protocol (MCP) to extend agent capabilities. When a task runs, Optio resolves which connections apply, starts the corresponding MCP servers in the pod, and the agent can use them as tools.

How It Works

Connections follow a three-layer architecture:

1. Providers — catalog entries that define a service type (e.g., “Notion”, “PostgreSQL”). Built-in providers ship with Optio; you can also create custom ones.
2. Connections — configured instances of a provider with your API keys and settings. For example, “Production Notion” with your team's integration token.
3. Assignments — rules that control which repos and agent types can access a connection, with permission levels (read, readwrite, full).

Built-in Providers

Creating a Connection

Navigate to Connections in the dashboard. Select a provider from the catalog, fill in the configuration (API keys, tokens, URLs), and optionally configure access control.

POST /api/connections
{
  "name": "Team Notion",
  "providerId": "<notion-provider-id>",
  "config": {
    "NOTION_TOKEN": "ntn_..."
  },
  "scope": "global",
  "enabled": true
}

By default, new connections are globally available to all repos and agent types. Use assignments to restrict access.

Custom MCP Servers

If you have an MCP server not in the built-in catalog, use the “Custom MCP Server” provider. Specify the command, arguments, and environment variables:

POST /api/connections
{
  "name": "Internal Docs Server",
  "providerId": "<custom-mcp-provider-id>",
  "config": {
    "command": "npx",
    "args": ["-y", "@myorg/docs-mcp-server"],
    "env": { "DOCS_API_KEY": "..." }
  },
  "scope": "global",
  "enabled": true
}

HTTP APIs

For REST APIs that aren't MCP-compatible, use the “HTTP API” provider. Supports no-auth, API key, and bearer token authentication.

Access Control

Assignments control which repos and agent types can use a connection. Each assignment specifies:

• Repository — a specific repo, or all repos (global)
• Agent types — restrict to specific agents (e.g., only Claude Code), or allow all
• Permission — read, readwrite, or full

POST /api/connections/:id/assignments
{
  "repoId": "repo-uuid",
  "agentTypes": ["claude-code"],
  "permission": "readwrite"
}

How Connections Are Injected

When a task runs, the task worker resolves applicable connections:

1. Looks up enabled connections matching the task's workspace
2. Filters by assignment rules (repo URL and agent type)
3. Builds MCP configuration entries with resolved secrets and environment variables
4. Writes the configuration into the agent pod's .mcp.json
5. The agent discovers and uses the MCP servers as tools during execution

Secrets are resolved at runtime and injected into the pod environment. They are never exposed in the web UI or API responses.

Health Checking

Each connection tracks its health status: healthy, error, or unknown. Test a connection from the dashboard or via the API:

POST /api/connections/:id/test

Managing Connections

Next Steps