> ## Documentation Index > Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt > Use this file to discover all available pages before exploring further. # Connecting MCP Servers > Add stdio and HTTP MCP servers to a Pioneer gateway. Add MCP servers from the desktop app while connected to the gateway that should own the integration. Pioneer connects to servers that implement [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro). Those servers can expose tools, resources, prompts, and workflows to the gateway. Before you add one, decide where it belongs. A work MCP server should usually live on the work gateway. A personal helper should live on the home or local gateway. An unfamiliar server should be tested in a sandbox first. ## Install from the desktop app In the desktop app, connect to the gateway where the MCP server should run. Click the MCP icon in the bottom bar, click **Install**, paste the MCP JSON config into the config field, and submit it. Pioneer reads the JSON, validates each server under `mcpServers`, stores secret values in the gateway secret store, saves redacted server settings, and starts or connects to enabled servers. ## Stdio servers Use stdio when Pioneer should launch the MCP server as a local child process. For stdio, the command in the JSON must already be available on the gateway host. For a remote gateway, install that command on the remote machine, not on your laptop. Paste a config with a top-level `mcpServers` object: ```json theme={null} { "mcpServers": { "resend": { "command": "npx", "args": ["-y", "resend-mcp"], "env": { "RESEND_API_KEY": "re_xxxxxxxxx" } } } } ``` The server name, such as `resend`, must use letters, numbers, `_`, or `-`. Use `command` for the executable, `args` for command arguments, and `env` for environment variables passed to that server. You can also set `cwd` when the command must start from a specific directory. ## HTTP servers Use HTTP when the MCP server is already running as a service. Start the service outside Pioneer, confirm the gateway can reach its URL, then install it from the MCP screen with a JSON config like this: ```json theme={null} { "mcpServers": { "resend": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer re_xxxxxxxxx" } } } } ``` Use `url` for the MCP HTTP endpoint and `headers` for authentication or routing headers. The URL must use `http` or `https`. If the gateway is remote, test connectivity from the remote host. ## Common config fields Every server config lives under `mcpServers` and uses the object key as the server name. | Field | Use | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `command` | Stdio server executable. Mutually exclusive with `url`. | | `args` | Optional stdio command arguments. | | `cwd` | Optional working directory for a stdio server. | | `env` | Optional environment variables for a stdio server. | | `url` | HTTP MCP endpoint. Mutually exclusive with `command`. | | `headers` | Optional HTTP headers for an HTTP server. | | `enabled` | Enables the server when `true`. | | `disabled` | Disables the server when `true`. Do not set both `enabled` and `disabled`. | | `allow_implicit_invocation` | Allows agents to consider the server automatically when `true`. New installs default to `false`; keep it `false` for explicit-only use. | | `required` | Marks the server as required for the configured scope. | | `startup_timeout_sec` | Optional startup timeout. | | `tool_timeout_sec` | Optional timeout for MCP tool calls. | ## Secrets Do not paste MCP secrets into chat prompts. Put API keys, tokens, and other credentials in the MCP JSON `env` or `headers` fields, or in the gateway environment when your server reads credentials from there. Pioneer stores secret values from `env`, `headers`, tokens, and authorization fields in the gateway secret store. Diagnostics, source references, and list/detail responses use redacted data instead of raw values. When you update or uninstall an MCP server, Pioneer cleans up stale MCP secret references after the server settings are updated. If you need to inspect or clean orphaned MCP secrets explicitly, use `pioneer secrets status` and `pioneer secrets garbage-collection`. ## Health and first test After saving a server, Pioneer should discover its tools, resources, templates, and prompts. If it fails, the most common causes are a missing command, invalid environment variable, auth failure, unreachable HTTP endpoint, or a server that starts but advertises no tools. Review the discovered tools before enabling implicit invocation. Keep new MCP servers not implicit until you understand what their tools can read, write, or call. Use a read-only first prompt: ```text theme={null} List the MCP tools available in this workspace and explain what each one can do. Do not call them yet. ``` Then call one low-risk tool and inspect the timeline. ## Use in a thread To use an explicit-only MCP capability, open a thread, click the composer add button, and choose **Add MCP**. Select either the whole server or specific tools. Selecting the server exposes that server's allowed tools for the turn; selecting tools exposes only those raw MCP tools. The selection appears as attachment chips in the composer and in the sent user message. It is sent as turn capability metadata, not as ordinary message text. ## Further reading * [MCP Architecture](/architecture/mcp) explains config parsing, runtime state, catalog refresh, and policy. * [Secret Storage](/architecture/secrets) explains how MCP secrets are redacted and referenced. * [Agent Loop](/architecture/agent-loop) explains how explicit MCP selections are materialized for one turn.