Connecting MCP Servers

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. 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:

{
  "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:

{
  "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:

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.

Getting Started

Desktop App

Mobile App

Providers

Skills

MCP Servers

Tasks & Automation

Configuration

CLI

Connecting MCP Servers

Install from the desktop app

Stdio servers

HTTP servers

Common config fields

Secrets

Health and first test

Use in a thread

Further reading

​Install from the desktop app

​Stdio servers

​HTTP servers

​Common config fields

​Secrets

​Health and first test

​Use in a thread

​Further reading

Install from the desktop app

Stdio servers

HTTP servers

Common config fields

Secrets

Health and first test

Use in a thread

Further reading