MCP server¶

AiFlow can plug into an external MCP (Model Context Protocol) client, Claude Desktop, another agent framework, an internal copilot, as a tool provider. Once connected, that client can place outbound calls, search an agent's knowledge base, fetch call transcripts, discover agents, record events, look up contacts, invoke custom tools, and delegate tasks to an Orchestrator, all through the same Streamable HTTP transport most MCP clients already speak.

This is the opposite direction from an AiFlow agent calling out to a third-party MCP server, which is covered separately in MCP server connections.

Connecting¶

The server is mounted at:

https://api.your-domain.com/api/v1/mcp/

The trailing slash matters

Requesting the URL without the trailing slash gets a 307 redirect to the version with one. Some MCP clients don't follow redirects automatically, so always configure the trailing-slash form directly to avoid a connection that silently fails.

Authenticate with an API key carrying at least one mcp:* scope, sent as a bearer token. See Authentication for how API keys work in general, and API keys for creating one.

A generic MCP client config looks like:

{
  "mcpServers": {
    "aiflow": {
      "url": "https://api.your-domain.com/api/v1/mcp/",
      "headers": { "Authorization": "Bearer af_live_..." }
    }
  }
}

The exact shape depends on your specific MCP client; the URL and the bearer header above are the two things every client needs.

Scopes¶

Each tool needs one scope, so a key can do exactly what you tick when you create it, and nothing more.

Scope	Grants
`mcp:calls`	`place_outbound_call`
`mcp:knowledge`	`search_knowledge_base`
`mcp:transcripts`	`fetch_call_transcript`
`mcp:agents`	`list_agents`, `get_agent_status`
`mcp:events`	`record_event`
`mcp:recall`	`lookup_end_user`
`mcp:custom_tools`	`call_custom_tool`
`mcp:orchestrate`	`delegate_task_to_orchestrator`

mcp:tools is the original, pre-split scope. It still works, as an alias for mcp:calls, mcp:knowledge, and mcp:transcripts together. It never grows to cover a capability added after it, and there is no mcp:* wildcard: a key is only ever as broad as its explicit scope list.

mcp:events, mcp:recall, mcp:custom_tools, and mcp:orchestrate also need the deployment to be licensed for the matching capability; calls to those tools otherwise return a plain error result.

Agent scoping¶

An API key's agent scope, the same one described in Authentication, controls what the key can do here too:

A key created with agent_id unset (any agent) can use every tool for every agent in your deployment.
A key scoped to one specific agent can only call agent-scoped tools for that agent. fetch_call_transcript also checks the transcript's own agent, so a scoped key can't read another agent's transcript even by guessing its ID; list_agents returns only that agent; delegate_task_to_orchestrator refuses an agent-pinned key, since delegation is not agent-scoped; lookup_end_user reads deployment-wide contact data and is not narrowed by the pin.

Tools¶

Tool	Arguments	Scope	Notes
`place_outbound_call`	`agent_id`, `phone_number`, `context` (nullable)	`mcp:calls`	Queues a real outbound call through the same durable queue an event-triggered call uses.
`search_knowledge_base`	`agent_id`, `query`	`mcp:knowledge`	Same retrieval an agent's own `search_knowledge_base` tool uses mid-conversation.
`fetch_call_transcript`	`call_id`	`mcp:transcripts`	Returns the full turn-by-turn transcript as plain text.
`list_agents`	none	`mcp:agents`	One line per agent: `id`, `slug`, `name`, `status`, tab-separated.
`get_agent_status`	`agent_id`	`mcp:agents`	Lifecycle state, model, and whether a phone number is attached.
`record_event`	`agent_id`, `event_type`, `payload` (nullable)	`mcp:events`	Records an event and evaluates the agent's triggers, exactly as posting to its events endpoint does.
`lookup_end_user`	`phone_number` (nullable), `email` (nullable)	`mcp:recall`	Returns a stored contact's remembered profile.
`call_custom_tool`	`agent_id`, `tool_name`, `arguments` (nullable)	`mcp:custom_tools`	Invokes one of that agent's admin-defined custom HTTP tools by name.
`delegate_task_to_orchestrator`	`orchestrator_slug`, `task_instruction`	`mcp:orchestrate`	Runs a full, bounded Orchestrator loop and returns its final answer.

A request with a missing or wrongly-scoped key fails at the per-tool call, with an error result, not a connection-level rejection; see Errors & rate limits for how AiFlow reports failures in general.

Security notes¶

DNS-rebinding protection is on. The deployment only accepts requests whose Host and Origin headers match its own configured public URL (plus localhost for local development). If every connection attempt fails with a 421 Misdirected Request, that's almost always a misconfigured public URL on the deployment side, not something you can fix from the client; flag it to whoever administers the deployment.
Every tool call is logged. Calls through this server are recorded in the deployment's admin audit log, keyed by the API key used. Grant each key only the mcp:* scopes the integration actually needs, with the same care you'd take with an events:write key.
delegate_task_to_orchestrator is loop-guarded across instances. Every federated delegation carries a hop count and a chain trace id; a deployment refuses a call past FEDERATION_MAX_HOPS or one whose trace it has already handled, returning a plain error result rather than looping. See Federation.