Pioneer implements MCP as a gateway-owned client runtime. The desktop app configures MCP servers, but the gateway host starts stdio servers, connects to HTTP servers, stores catalogs, resolves secrets, and calls MCP tools during agent turns.MCP connects Pioneer to external tool systems. Pioneer does not load MCP servers as trusted in-process plugins. It manages them as external runtimes with transport, policy, status, catalogs, secrets, and audit state.
MCP server commands and HTTP reachability are evaluated from the gateway host. With a remote gateway, install commands and test network access on that host.
An MCP server has startup behavior, authentication, a changing catalog, errors, retry state, and secrets. Pioneer needs a runtime service to manage that state.pioneer-mcp owns protocol-facing MCP concerns such as config parsing, transports, clients, catalogs, and runtime sessions. McpService in the gateway owns gateway-facing concerns: database rows, live task supervision, notifications, tool materialization, and calls from the agent’s tool runtime.
Each server must define exactly one transport: command for stdio or url for streamable HTTP. Server names must match ^[A-Za-z0-9_-]{1,64}$.Common optional fields include required, startup_timeout_sec, tool_timeout_sec, and timeout. Policy flags such as enabled state and implicit invocation are stored as installation/policy state, not required in the basic config examples.
Environment variables and HTTP headers can contain secrets. The config parser materializes secret refs, stores secret values through the gateway keystore, and stores redacted transport/source data in gateway.db. Runtime sessions resolve secrets through McpSecretResolver when a server task starts.The installation remains readable and auditable without copying raw secret values into catalog snapshots or list responses.When an MCP install is updated or uninstalled, the gateway deletes stale keystore refs after the database change succeeds. The CLI also exposes pioneer secrets garbage-collection for orphan MCP secret values that need an explicit cleanup pass.
McpService::reload_workspace loads installed workspace servers from the database and compares them with currently running tasks. Disabled servers are stopped and reported as disabled. Changed fingerprints cause a restart. Removed servers are stopped.For enabled servers, McpService starts a task that connects through RmcpRuntimeConnector, obtains the initial catalog, stores status, watches server events, refreshes catalogs, and accepts tool-call commands over an internal channel.Runtime states include not_started, disabled, starting, ready, degraded, auth_required, failed, stopping, stopped, and restarting.
When a server becomes live, Pioneer stores a catalog snapshot: server info, server instructions hash, tools, resources, resource templates, prompts, catalog version, and generation timestamp.Catalog changes publish mcp/server/catalog_changed and increment the gateway MCP snapshot version. The agent uses the live snapshot and stored catalog to decide which MCP tools can be materialized for a turn.
MCP policy is per gateway and per workspace. A server can be installed but disabled. A server can also be installed and enabled without allowing implicit tool exposure.At turn time, the agent asks AgentMcpToolProvider for availability and materialized tools. The request includes implicit exposure state plus explicit composer selections from TurnStartParams.capabilities: selected servers and selected raw tools.MCP projection is bounded deliberately. The current defaults allow up to 512 tools, 3 MiB of combined tool schemas, and 16 concurrent MCP calls per turn. The gateway, provider configuration, and CLI bridge validate and apply the same limits so a large catalog cannot bypass the execution budget at a later layer. Invalid limits are rejected before an agent session starts.McpService reloads the workspace, checks installation policy, checks runtime state, loads the catalog snapshot, and builds dynamic tool descriptors. A selected server exposes that server’s allowed catalog tools for the turn. A selected tool exposes only that raw tool. If a server-level selection exists, individual tool selections for the same server are treated as duplicates at the UI/state boundary and the server selection wins.Blocked, missing, disabled, unavailable, unsupported, or catalog-missing selections produce rejected turn capability diagnostics instead of breaking the turn.MCP tools are not represented by prompt text. They materialize into ChatRequest.tools as dynamic extension tools. If the provider does not support tool calling, explicit MCP capabilities are rejected as provider-unsupported.When the model calls a materialized MCP tool, the tool runtime sends the call back to McpService. The service forwards it to the live server task, waits for McpToolCallResult, and records audit/binding data.The model never calls an MCP server directly. The call passes through the Pioneer tool runtime and gateway MCP service, so output policy, diagnostics, audit records, turn bindings, and runtime errors remain under Pioneer control.
For stdio servers, command, args, cwd, and env are evaluated on the gateway host. For HTTP servers, the gateway host must be able to reach the URL. If the gateway runs remotely, MCP connectivity must be tested from that remote machine, not from the desktop client.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Pioneer","colors":{"primary":"#1071FF","light":"#1071FF","dark":"#1071FF"},"logo":{"light":"https://mintcdn.com/pioneer-de55fe0a/tZ9pz7n2azdrHkvQ/logo/light.svg?fit=max\u0026auto=format\u0026n=tZ9pz7n2azdrHkvQ\u0026q=85\u0026s=d8d6800d6d5db54cd4de0c15b607985e","dark":"https://mintcdn.com/pioneer-de55fe0a/tZ9pz7n2azdrHkvQ/logo/dark.svg?fit=max\u0026auto=format\u0026n=tZ9pz7n2azdrHkvQ\u0026q=85\u0026s=85c34d5080e7ae8ac47648719071987a"},"favicon":"https://mintcdn.com/pioneer-de55fe0a/tZ9pz7n2azdrHkvQ/favicon.svg?fit=max\u0026auto=format\u0026n=tZ9pz7n2azdrHkvQ\u0026q=85\u0026s=ef99e0f25527be4b2420f0a42e0fba0d","navbar":{"links":[{"href":"https://github.com/pioneerdotai/pioneer","label":"GitHub"}]},"footer":{"socials":{"github":"https://github.com/pioneerdotai/pioneer"}},"contextual":{"options":["copy","view","claude","cursor"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"pioneer-de55fe0a","hasAudioNarration":false,"actualSubdomain":"pioneer-de55fe0a","customDomains":["docs.getpioneer.dev"],"gitSource":{"type":"github","owner":"pioneerdotai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ac3800597e99dac9a9a72d3","collectionId":"4b62170d-9ca5-4ddb-b60d-c7af85af8524","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ac3800597e99dac9a9a72d3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ac3800597e99dac9a9a72d3","clientVersion":"0.0.4054","searchFilterCounts":[{"language":"default","tag":"User Guide","count":33},{"language":"default","tag":"Architecture","count":27},{"language":"default","tag":"Protocol Reference","count":17},{"language":"default","tag":"Subsystems","count":15},{"language":"default","tag":"Features","count":11},{"language":"default","tag":"Core Systems","count":9},{"language":"default","tag":"Desktop App","count":9},{"language":"default","tag":"Getting Started","count":6},{"language":"default","tag":"Workspace \u0026 Threads","count":5},{"language":"default","tag":"Skills","count":5}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"architecture/mcp","slug":"/architecture/mcp","pageMetadata":{"title":"MCP","description":"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.","href":"/architecture/mcp"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Pioneer implements MCP as a gateway-owned client runtime. The desktop app configures MCP servers, but the gateway host starts stdio servers, connects to HTTP servers, stores catalogs, resolves secrets, and calls MCP tools during agent turns.`}),`\n`,_jsx(_components.p,{children:`MCP connects Pioneer to external tool systems. Pioneer does not load MCP servers as trusted in-process plugins. It manages them as external runtimes with transport, policy, status, catalogs, secrets, and audit state.`}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`MCP server commands and HTTP reachability are evaluated from the gateway host. With a remote gateway, install commands and test network access on that host.`})}),`\n`,_jsx(Heading,{level:`2`,id:`why-this-layer-exists`,children:`Why this layer exists`}),`\n`,_jsx(_components.p,{children:`An MCP server has startup behavior, authentication, a changing catalog, errors, retry state, and secrets. Pioneer needs a runtime service to manage that state.`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`pioneer-mcp`}),` owns protocol-facing MCP concerns such as config parsing, transports, clients, catalogs, and runtime sessions. `,_jsx(_components.code,{children:`McpService`}),` in the gateway owns gateway-facing concerns: database rows, live task supervision, notifications, tool materialization, and calls from the agent’s tool runtime.`]}),`\n`,_jsx(Heading,{level:`2`,id:`components`,children:`Components`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Component`}),_jsx(_components.th,{children:`Code`}),_jsx(_components.th,{children:`Responsibility`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Config parser`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`crates/mcp/src/config.rs`})}),_jsxs(_components.td,{children:[`Parses `,_jsx(_components.code,{children:`mcpServers`}),` JSON, validates names/transports, extracts secrets, creates install plans.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Domain model`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`crates/mcp/src/domain.rs`})}),_jsx(_components.td,{children:`Installation, transport, scope, source, policy, availability, runtime state, and secret ref types.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Runtime connector`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`crates/mcp/src/runtime/mod.rs`})}),_jsxs(_components.td,{children:[`Connects to MCP servers and exposes `,_jsx(_components.code,{children:`McpRuntimeSession`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Clients`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`crates/mcp/src/client/*`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`rmcp`}),`-based stdio and streamable HTTP clients.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Gateway service`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`crates/gateway/src/mcp_service.rs`})}),_jsx(_components.td,{children:`Starts/stops/restarts server tasks, tracks snapshots, stores catalogs, publishes status, materializes tools.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Gateway handlers`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`crates/gateway/src/message/mcp/*`})}),_jsx(_components.td,{children:`JSON-RPC methods for install, list, policy, restart, uninstall, and details.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`install-config`,children:`Install config`}),`\n`,_jsx(_components.p,{children:`Pioneer accepts the familiar top-level shape:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`11`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"mcpServers\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"server_name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"command\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"some-command\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"args\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"--flag\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"env\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"API_KEY\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"secret-value\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`or:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`10`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`10`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"mcpServers\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"server_name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"url\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://example.com/mcp\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"headers\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"Authorization\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bearer secret-value\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Each server must define exactly one transport: `,_jsx(_components.code,{children:`command`}),` for stdio or `,_jsx(_components.code,{children:`url`}),` for streamable HTTP. Server names must match `,_jsx(_components.code,{children:`^[A-Za-z0-9_-]{1,64}$`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`Common optional fields include `,_jsx(_components.code,{children:`required`}),`, `,_jsx(_components.code,{children:`startup_timeout_sec`}),`, `,_jsx(_components.code,{children:`tool_timeout_sec`}),`, and `,_jsx(_components.code,{children:`timeout`}),`. Policy flags such as enabled state and implicit invocation are stored as installation/policy state, not required in the basic config examples.`]}),`\n`,_jsx(Heading,{level:`2`,id:`secrets-and-redaction`,children:`Secrets and redaction`}),`\n`,_jsxs(_components.p,{children:[`Environment variables and HTTP headers can contain secrets. The config parser materializes secret refs, stores secret values through the gateway keystore, and stores redacted transport/source data in `,_jsx(_components.code,{children:`gateway.db`}),`. Runtime sessions resolve secrets through `,_jsx(_components.code,{children:`McpSecretResolver`}),` when a server task starts.`]}),`\n`,_jsx(_components.p,{children:`The installation remains readable and auditable without copying raw secret values into catalog snapshots or list responses.`}),`\n`,_jsxs(_components.p,{children:[`When an MCP install is updated or uninstalled, the gateway deletes stale keystore refs after the database change succeeds. The CLI also exposes `,_jsx(_components.code,{children:`pioneer secrets garbage-collection`}),` for orphan MCP secret values that need an explicit cleanup pass.`]}),`\n`,_jsx(Heading,{level:`2`,id:`runtime-lifecycle`,children:`Runtime lifecycle`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`McpService::reload_workspace`}),` loads installed workspace servers from the database and compares them with currently running tasks. Disabled servers are stopped and reported as disabled. Changed fingerprints cause a restart. Removed servers are stopped.`]}),`\n`,_jsxs(_components.p,{children:[`For enabled servers, `,_jsx(_components.code,{children:`McpService`}),` starts a task that connects through `,_jsx(_components.code,{children:`RmcpRuntimeConnector`}),`, obtains the initial catalog, stores status, watches server events, refreshes catalogs, and accepts tool-call commands over an internal channel.`]}),`\n`,_jsxs(_components.p,{children:[`Runtime states include `,_jsx(_components.code,{children:`not_started`}),`, `,_jsx(_components.code,{children:`disabled`}),`, `,_jsx(_components.code,{children:`starting`}),`, `,_jsx(_components.code,{children:`ready`}),`, `,_jsx(_components.code,{children:`degraded`}),`, `,_jsx(_components.code,{children:`auth_required`}),`, `,_jsx(_components.code,{children:`failed`}),`, `,_jsx(_components.code,{children:`stopping`}),`, `,_jsx(_components.code,{children:`stopped`}),`, and `,_jsx(_components.code,{children:`restarting`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`catalogs`,children:`Catalogs`}),`\n`,_jsx(_components.p,{children:`When a server becomes live, Pioneer stores a catalog snapshot: server info, server instructions hash, tools, resources, resource templates, prompts, catalog version, and generation timestamp.`}),`\n`,_jsxs(_components.p,{children:[`Catalog changes publish `,_jsx(_components.code,{children:`mcp/server/catalog_changed`}),` and increment the gateway MCP snapshot version. The agent uses the live snapshot and stored catalog to decide which MCP tools can be materialized for a turn.`]}),`\n`,_jsx(Heading,{level:`2`,id:`policy-and-tool-materialization`,children:`Policy and tool materialization`}),`\n`,_jsx(_components.p,{children:`MCP policy is per gateway and per workspace. A server can be installed but disabled. A server can also be installed and enabled without allowing implicit tool exposure.`}),`\n`,_jsxs(_components.p,{children:[`At turn time, the agent asks `,_jsx(_components.code,{children:`AgentMcpToolProvider`}),` for availability and materialized tools. The request includes implicit exposure state plus explicit composer selections from `,_jsx(_components.code,{children:`TurnStartParams.capabilities`}),`: selected servers and selected raw tools.`]}),`\n`,_jsx(_components.p,{children:`MCP projection is bounded deliberately. The current defaults allow up to 512 tools, 3 MiB of combined tool schemas, and 16 concurrent MCP calls per turn. The gateway, provider configuration, and CLI bridge validate and apply the same limits so a large catalog cannot bypass the execution budget at a later layer. Invalid limits are rejected before an agent session starts.`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`McpService`}),` reloads the workspace, checks installation policy, checks runtime state, loads the catalog snapshot, and builds dynamic tool descriptors. A selected server exposes that server’s allowed catalog tools for the turn. A selected tool exposes only that raw tool. If a server-level selection exists, individual tool selections for the same server are treated as duplicates at the UI/state boundary and the server selection wins.`]}),`\n`,_jsx(_components.p,{children:`Blocked, missing, disabled, unavailable, unsupported, or catalog-missing selections produce rejected turn capability diagnostics instead of breaking the turn.`}),`\n`,_jsxs(_components.p,{children:[`MCP tools are not represented by prompt text. They materialize into `,_jsx(_components.code,{children:`ChatRequest.tools`}),` as dynamic extension tools. If the provider does not support tool calling, explicit MCP capabilities are rejected as provider-unsupported.`]}),`\n`,_jsxs(_components.p,{children:[`When the model calls a materialized MCP tool, the tool runtime sends the call back to `,_jsx(_components.code,{children:`McpService`}),`. The service forwards it to the live server task, waits for `,_jsx(_components.code,{children:`McpToolCallResult`}),`, and records audit/binding data.`]}),`\n`,_jsx(_components.p,{children:`The model never calls an MCP server directly. The call passes through the Pioneer tool runtime and gateway MCP service, so output policy, diagnostics, audit records, turn bindings, and runtime errors remain under Pioneer control.`}),`\n`,_jsx(Heading,{level:`2`,id:`local-versus-remote-gateways`,children:`Local versus remote gateways`}),`\n`,_jsxs(_components.p,{children:[`For stdio servers, `,_jsx(_components.code,{children:`command`}),`, `,_jsx(_components.code,{children:`args`}),`, `,_jsx(_components.code,{children:`cwd`}),`, and `,_jsx(_components.code,{children:`env`}),` are evaluated on the gateway host. For HTTP servers, the gateway host must be able to reach the URL. If the gateway runs remotely, MCP connectivity must be tested from that remote machine, not from the desktop client.`]}),`\n`,_jsx(Heading,{level:`2`,id:`related-pages`,children:`Related pages`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/tools`,children:`Tools System`}),` explains how MCP tools become model-visible dynamic tools.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/gateway`,children:`Gateway`}),` explains why MCP processes are gateway-owned.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/skills`,children:`Skills Architecture`}),` explains the parallel extension system for skills.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/persistence`,children:`Persistence Layer`}),` explains MCP installations, catalog snapshots, audit events, and turn bindings.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/secrets`,children:`Secret Storage`}),` explains where MCP secret values live.`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"MCP","description":"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.","href":"/architecture/mcp"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Why this layer exists","slug":"why-this-layer-exists","depth":2,"children":[]},{"title":"Components","slug":"components","depth":2,"children":[]},{"title":"Install config","slug":"install-config","depth":2,"children":[]},{"title":"Secrets and redaction","slug":"secrets-and-redaction","depth":2,"children":[]},{"title":"Runtime lifecycle","slug":"runtime-lifecycle","depth":2,"children":[]},{"title":"Catalogs","slug":"catalogs","depth":2,"children":[]},{"title":"Policy and tool materialization","slug":"policy-and-tool-materialization","depth":2,"children":[]},{"title":"Local versus remote gateways","slug":"local-versus-remote-gateways","depth":2,"children":[]},{"title":"Related pages","slug":"related-pages","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"pioneer-de55fe0a","siteName":"Pioneer","title":"MCP - Pioneer","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-07-26T07:20:08.971Z","originalFileLocation":"architecture/mcp.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Pioneer\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"MCP - Pioneer\">\u003cmeta data-mint-head property=\"og:description\" content=\"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Pioneer\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.getpioneer.dev/architecture/mcp\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://pioneer-de55fe0a.mintlify.app/_mintlify/api/og/v2?division=Subsystems\u0026amp;title=MCP\u0026amp;description=MCP+install+parsing%2C+runtime+sessions%2C+catalogs%2C+policy%2C+and+dynamic+tool+calls.\u0026amp;theme=a76fe18d0f0f07dff9f24952\u0026amp;signature=69fa55325ac0da9d4ae651124f38e21f0423755f206b775bdace2884efcd6fd5\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"MCP - Pioneer\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://pioneer-de55fe0a.mintlify.app/_mintlify/api/og/v2?division=Subsystems\u0026amp;title=MCP\u0026amp;description=MCP+install+parsing%2C+runtime+sessions%2C+catalogs%2C+policy%2C+and+dynamic+tool+calls.\u0026amp;theme=a76fe18d0f0f07dff9f24952\u0026amp;signature=69fa55325ac0da9d4ae651124f38e21f0423755f206b775bdace2884efcd6fd5\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/pioneer-de55fe0a/DnN60egLYTK2Subm/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Pioneer\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#1071FF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.getpioneer.dev/architecture/mcp\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/architecture/mcp.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.getpioneer.dev/#organization\",\"name\":\"Pioneer\",\"url\":\"https://docs.getpioneer.dev\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/pioneer-de55fe0a/tZ9pz7n2azdrHkvQ/logo/light.svg?fit=max\u0026auto=format\u0026n=tZ9pz7n2azdrHkvQ\u0026q=85\u0026s=d8d6800d6d5db54cd4de0c15b607985e\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.getpioneer.dev#website\",\"name\":\"Pioneer\",\"url\":\"https://docs.getpioneer.dev\",\"publisher\":{\"@id\":\"https://docs.getpioneer.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.getpioneer.dev/architecture/mcp#webpage\",\"url\":\"https://docs.getpioneer.dev/architecture/mcp\",\"name\":\"MCP\",\"description\":\"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.\",\"dateModified\":\"2026-07-26T07:20:08.971Z\",\"isPartOf\":{\"@id\":\"https://docs.getpioneer.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.getpioneer.dev/architecture/mcp#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.getpioneer.dev/architecture/mcp#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Subsystems\",\"item\":\"https://docs.getpioneer.dev/architecture/agent-domain\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"MCP\",\"item\":\"https://docs.getpioneer.dev/architecture/mcp\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.getpioneer.dev/architecture/mcp#article\",\"headline\":\"MCP\",\"name\":\"MCP\",\"description\":\"MCP install parsing, runtime sessions, catalogs, policy, and dynamic tool calls.\",\"url\":\"https://docs.getpioneer.dev/architecture/mcp\",\"mainEntityOfPage\":{\"@id\":\"https://docs.getpioneer.dev/architecture/mcp#webpage\"},\"dateModified\":\"2026-07-26T07:20:08.971Z\",\"publisher\":{\"@id\":\"https://docs.getpioneer.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.getpioneer.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Pioneer\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Pioneer","nav":{"global":null,"tabs":[{"tab":"User Guide","pages":[{"title":"User Guide","href":""}]},{"tab":"Architecture","groups":[{"group":"Overview","pages":[{"title":"Architecture Overview","href":"/architecture/overview"},{"title":"Crate Map","href":"/architecture/crates"}]},{"group":"Core Systems","pages":[{"title":"Gateway","href":"/architecture/gateway"},{"title":"Identity, authentication, and authorization","href":"/architecture/identity-and-authorization"},{"title":"Client Architecture","href":"/architecture/clients"},{"title":"Agent Loop","href":"/architecture/agent-loop"},{"title":"CLI Runtime Architecture","href":"/architecture/cli-runtime"},{"title":"Hook Runtime","href":"/architecture/hooks"},{"title":"Protocol Layer","href":"/architecture/protocol"},{"title":"Permission \u0026 Sandboxing System","href":"/architecture/permissions"},{"title":"Tools System","href":"/architecture/tools"}]},{"group":"Subsystems","pages":[{"title":"Agent domain and delegation","href":"/architecture/agent-domain"},{"title":"Provider System","href":"/architecture/providers"},{"title":"Skills","href":"/architecture/skills"},{"title":"Tasks And Subagents","href":"/architecture/tasks"},{"title":"Artifact Store","description":"Workspace-scoped file storage, metadata, bindings, previews, uploads, downloads, and provider attachment reuse.","href":"/architecture/artifacts"},{"title":"MCP","href":"/architecture/mcp"},{"title":"Memory","description":"Durable agent memory: control plane, memvid capsules, hooks, recall, semantic writes, candidates, and post-turn extraction.","href":"/architecture/memory"},{"title":"Thread Episodic Context","href":"/architecture/thread-episodic-context"},{"title":"Persistence Layer","href":"/architecture/persistence"},{"title":"Patch history and file mutation","href":"/architecture/patch-history"},{"title":"Observability and runtime maintenance","href":"/architecture/observability"},{"title":"Secret storage","href":"/architecture/secrets"},{"title":"Remote Access Architecture","href":"/architecture/remote-access"},{"title":"Prompt And Context","href":"/architecture/prompt"},{"title":"AGENTS.md Architecture","href":"/architecture/agents-md"}]},{"group":"Contributing","pages":[{"title":"Contributing","icon":"code-pull-request","href":"/contributing"}]}]},{"tab":"Protocol Reference","pages":[{"title":"Protocol Reference","href":"/protocol/introduction"}]}]},"basePath":"","title":"MCP - Pioneer","buildId":"dpl_345ReqzYaAjzS9QpeJemsKdb7KDj","deploymentId":"dpl_345ReqzYaAjzS9QpeJemsKdb7KDj","dynamics":[],"chunks":[]}
