Connections (MCP)

A Connection (internally an MCP Server) is an external Model Context Protocol  server that you register once and then assign to one or more Assistants (Agents). Once assigned, the server’s tools become available to that Assistant when it runs — filesystem access, a database client, a web API wrapper, and so on.

Connections are how you extend an Assistant beyond its built-in capabilities without writing custom code. You define how to start the server (a command plus arguments and environment variables), and RondoFlow wires it into the Assistant’s runtime configuration.

Two ways an Assistant gets tools

A single Assistant can pull MCP servers from two independent sources, which RondoFlow merges at run time:

This split lets a Skill bring its own tools along with it, while you stay free to attach extra standalone Connections on top. A Skill’s mcpConfig is declared in its rondoflow.json manifest (or in the SKILL.md frontmatter that gets merged with it) and is also stdio-only — see Skills for how to bundle one.

Register a Connection

Open the MCP Connections panel and add a server. Which fields apply depends on the chosen transport:

In the UI, the form swaps between the local and remote fields as you pick the transport. For stdio, arguments are entered comma-separated and split into the args array, and environment variables are entered as key/value pairs. A typical local filesystem server looks like this:

Name:    filesystem
Type:    stdio
Command: npx
Args:    -y, @modelcontextprotocol/server-filesystem, /tmp

A remote server instead takes a URL and (optionally) an auth method:

Name:    docs-search
Type:    http
URL:     https://mcp.example.com/sse
Auth:    Bearer token

Authenticating a remote Connection

A remote (http / sse) Connection can carry an auth object so RondoFlow can reach a protected server. Four methods are supported:

At spawn time a remote Connection’s auth is resolved into request headers before the merged config is handed to the CLI: a bearer or custom header is injected directly, while OAuth2 client-credentials are first exchanged at the tokenUrl for a short-lived access token. A stdio Connection has no auth — it relies on env instead.

Add a Connection card on the canvas

Connections are also a first-class node (Card) on the Workspace (Canvas). Drag the Connection card (the plug icon, purple accent) from the palette onto the canvas, then draw an edge from it to an Assistant card. That visual link is an association edge — the same kind used by Skill and Safety Rule cards.

See The canvas for the full card catalog and edge types.

Assign a Connection to an Assistant

To remove access, detach the Connection from the Assistant. Detaching only removes the link — the Connection itself stays in your library. Deleting a Connection outright cascades: all of its Assistant assignments are removed automatically by the database.

How the merged config is built

When an Assistant runs, the MCP config builder assembles one mcpServers map from both sources:

The result is a structure shaped like this:

interface MergedMcpConfig {
  readonly mcpServers: Readonly<Record<string, McpServerConfig>>
  readonly conflicts: ReadonlyArray<{
    readonly name: string          // human-readable "command args"
    readonly sources: readonly string[]  // logical names that collided
  }>
}

Only the mcpServers map is forwarded to the spawned Claude Code CLI (as the --mcp-config argument); the conflicts list is internal metadata used for diagnostics. The serialized config is redacted in logged spawn arguments so secrets in env never reach logs.

Why namespacing matters

Because Skill-sourced servers are prefixed with the Skill name, two different Skills can each bundle a server called search without clobbering each other — they become web-tools/search and docs/search. Direct Connections keep their plain names, so you control those names directly through the unique name field.

Connections API

All routes return the standard { success, data?, error?, meta? } envelope. They sit behind the default-deny auth middleware: GET reads are open to any authenticated user, while the mutating verbs (POST/PATCH/DELETE, including assign/unassign) require the write capability — that is, an editor or higher role. See Users & roles for the capability matrix.

Manage Connections

Attach / detach to an Assistant

Create example:

curl -X POST http://localhost:3001/api/mcp-servers \
  -H 'content-type: application/json' \
  -d '{
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    "env": { "READONLY": "1" }
  }'

Remote (http/sse) Connection with bearer auth:

curl -X POST http://localhost:3001/api/mcp-servers \
  -H 'content-type: application/json' \
  -d '{
    "name": "docs-search",
    "type": "http",
    "url": "https://mcp.example.com/sse",
    "auth": { "type": "bearer", "token": "sk-..." }
  }'

Attach example:

curl -X POST http://localhost:3001/api/agents/AGENT_ID/mcp/SERVER_ID

Data model

Two tables back Connections:

model McpServer {
  id          String   @id @default(uuid())
  name        String   @unique
  description String?
  type        String   @default("stdio") // 'stdio' | 'http' | 'sse'
  command     String?  // stdio transport only
  args        String[]
  env         Json?
  url         String?  // http/sse transport only
  auth        Json?    // { type, ... } — secret fields encrypted at rest
  createdAt   DateTime @default(now())
 
  agents AgentMcpServer[]
}
 
model AgentMcpServer {
  agentId     String
  mcpServerId String
 
  agent     Agent     @relation(fields: [agentId], references: [id], onDelete: Cascade)
  mcpServer McpServer @relation(fields: [mcpServerId], references: [id], onDelete: Cascade)
 
  @@id([agentId, mcpServerId])
}

AgentMcpServer is a join table with a composite primary key, so each Assistant–Connection pairing is unique and deleting either side cascades the link away.

Related