Extending Quincy with MCP¶

Quincy comes with built-in tools for common tasks — reading files, listing directories, switching models, delegating to sub-agents. But what if you want an agent that can check your calendar, query a database, or control your smart home? That's where MCP comes in.

MCP (Model Context Protocol) is an open standard that lets AI agents connect to external tools and data sources. Think of MCP servers as plugins: each one exposes a set of tools that any compatible agent can use. There's a growing ecosystem of MCP servers for everything from GitHub and Slack to home automation and databases.

When you connect an MCP server to one of your Quincy agents, that agent gains access to all the tools the server provides — no custom code required.

MCP Bridges¶

The fastest way to connect an external MCP server is through an MCP bridge. A bridge wraps an external MCP server and exposes its tools through Quincy's tool pool — making them indistinguishable from built-in tools at the agent level. Bridges support two transports:

• stdio — spawns a local subprocess and communicates via stdin/stdout (great for locally installed MCP servers)
• HTTP — connects to a remote MCP server over Streamable HTTP (great for cloud-hosted or shared servers)

Creating a Bridge¶

Ask Quincy to create a bridge for you. The MCP Bridge Creator agent walks you through the process conversationally:

1. Tell Quincy what MCP server you want to connect (e.g., "connect the OmniFocus MCP server" or "connect https://api.example.com/mcp")
2. The creator agent scans the server to discover its tools — for HTTP servers, it tries .well-known/mcp discovery first, then falls back to a direct connection
3. Together you decide which tools to expose, what approval rules to set, and which agents should see them
4. The creator saves a signed configuration and hot-reloads it — the bridge is available immediately
5. Optionally, the creator can also build a companion agent configured to discover the new bridge via pool tags — so you get a ready-to-use specialist agent alongside the bridge

User-created bridges are automatically distinguished from built-in tools by a naming convention, so there's no risk of collisions.

What You Can Configure¶

When creating a bridge (or refining one later), you can control:

• Transport — stdio (spawn a local subprocess) or HTTP (connect to a remote URL over Streamable HTTP)
• Which tools are visible — filter which of the server's tools agents can see, using glob patterns
• Approval rules — allow reads automatically but require approval for writes, block destructive operations entirely, etc.
• Discovery tags — tag the bridge so agents can find it automatically through pool-based discovery
• Authentication — for HTTP bridges, bearer tokens stored in the macOS Keychain; for stdio bridges, environment variables with keychain: prefix resolution
• Connection mode — shared (default, efficient) or dedicated (each agent gets its own connection)
• Custom headers — for HTTP bridges, additional HTTP headers included in every request

Re-exposing Bridged Tools¶

Bridged tools can also be exposed to external agents — see Exposing Quincy's Tools as MCP Servers below. This turns Quincy into an MCP firewall: the bridge connects to the upstream server with full access, while the scoped registry controls exactly what external agents can see.

REST API Tools¶

Beyond MCP bridges, Quincy can wrap any REST API with an OpenAPI or Swagger spec as a set of tools. Ask Quincy to connect to a REST API and provide the spec URL — it handles authentication, token refresh, and tool generation automatically. This is useful for APIs that don't have an MCP server available.

The Sandbox and the Bridge¶

On macOS, Quincy runs inside the App Sandbox for security. This means it can't directly launch arbitrary processes (like MCP servers that need filesystem or network access beyond what the sandbox allows). The quincy-bridge binary runs outside the sandbox as a background service and hosts MCP server processes on Quincy's behalf. Communication between Quincy and the bridge happens over a local SSE connection. You don't need to manage the bridge manually — Quincy starts it automatically when needed.

graph LR
    subgraph Sandbox[App Sandbox]
        Quincy[Quincy Server]
    end

    subgraph Outside[Outside Sandbox]
        Bridge[quincy-bridge]
        MCP1[MCP Server A]
        MCP2[MCP Server B]
    end

    Quincy <-->|SSE| Bridge
    Bridge --> MCP1
    Bridge --> MCP2

Why Use MCP?¶

Quincy's built-in tools cover the basics, but they can't anticipate every workflow. MCP lets you extend any agent with exactly the capabilities it needs:

• Connect a task management agent to an MCP server for OmniFocus, Todoist, Linear, or any other task manager
• Give a research agent access to a web search MCP server
• Let a home automation agent talk to your smart devices through a HomeKit MCP server

The agent's system prompt tells it when to use these tools. The MCP server provides the how. You configure both through Quincy.

Adding an MCP Server to an Agent¶

Each agent can connect to one or more MCP servers. When you add an MCP server to an agent, you provide:

• A name — identifies the server (e.g., "todoist", "github")
• How to reach it — either a command to start a local process (stdio), or a URL for a remote server (http)

Quincy manages the connection lifecycle. It starts local MCP servers on demand, keeps connections alive while the agent is active, and shuts them down when they're no longer needed.

Quincy also ships with built-in MCP servers that run in-process — no external binary or network connection needed. For example, Quincy's own documentation is served as MCP resources via a built-in server, so agents can read docs without any setup. Built-in servers are registered automatically at startup.

Exposing Quincy's Tools as MCP Servers¶

Quincy isn't just a consumer of MCP servers — it can also expose its own tools as MCP servers for external agents to use. This lets other AI tools (like Claude Code, Cursor, or any MCP-compatible client) call Quincy's tools over HTTP.

The Scoped MCP Registry¶

Quincy's scoped MCP registry lets you choose exactly which tools to expose to external agents. For each MCP server (built-in or bridged), you specify which tools are visible using glob patterns — expose everything, just a few specific tools, or nothing at all.

By default, no MCP endpoints are exposed. You choose what to share.

For a complete listing of all built-in MCP servers, see the Tools & MCP Server Reference.

How External Agents Connect¶

External agents discover available servers via:

GET /v1/mcp-servers

This returns a list of exposed servers with their names, descriptions, and endpoint URLs. Each server has its own scoped endpoint that speaks the standard MCP protocol (Streamable HTTP transport), so any MCP-compatible client can connect to it. Each server only exposes its allowed tools — the rest of Quincy's tools are invisible to the external agent.

MCP Firewall¶

This is especially powerful with MCP Bridges. Bridge an external MCP server into Quincy with full access, then use the scoped registry to control exactly which tools external agents can reach. For example, you could bridge a task manager like OmniFocus or Todoist and expose only completion tools — external agents can mark tasks done but not delete them or access unrelated projects.

Secrets Stay in the Keychain¶

MCP servers often need credentials — API tokens, passwords, database connection strings. Quincy resolves these from the macOS Keychain at connection time. Your secrets are never written into any configuration file, and they're never included in conversations with the LLM.

This follows the same principle as the rest of Quincy's security model: the agent knows it can use a tool, but it never sees the credentials that make the tool work. See Security & Trust for the full picture.

Advanced: Shared and Dedicated Connections¶

By default, MCP connections are shared. If two agents both connect to the same MCP server, they reuse the same connection. This is efficient — one connection serves multiple agents.

Sometimes an agent needs its own private connection. If the MCP server maintains state per connection (like a database transaction), or if the agent needs isolation from other agents using the same server, you can mark the connection as dedicated. A dedicated connection belongs to one agent and isn't shared with anyone else.

For most MCP servers, shared connections work fine. Use dedicated connections when the server's documentation calls for it, or when you notice agents stepping on each other's toes.

Advanced: Automatic Tool Curation¶

Some MCP servers expose dozens of tools — more than a local model can effectively reason about in a single conversation. When this happens, Quincy automatically curates the tool list.

Curation uses a quick LLM call to assess each tool's relevance to the agent's purpose, then decides how to present them:

• High-value tools are registered individually with full descriptions, so the agent can call them directly
• Secondary tools are grouped together under a single entry, keeping them available without cluttering the agent's context
• Irrelevant or risky tools are omitted entirely

This happens behind the scenes — you don't need to configure it. The curation result is cached and only recalculated when the MCP server's tool list changes.