Skip to main content
MCP servers extend the gateway with external tools, resources, resource templates, and prompts. Pioneer follows the Model Context Protocol, while the Pioneer protocol manages installation, runtime state, policy, health, and catalog visibility around those servers. The gateway is the MCP host. If a desktop app is connected to a remote gateway, stdio server commands run on the remote machine and HTTP server URLs must be reachable from that remote machine.

​
Methods

MethodParamsResultPurpose
mcp/listMcpListParamsMcpListResponseList installed MCP servers for a workspace.
mcp/installMcpInstallParamsMcpInstallResponseInstall or update servers from MCP JSON config.
mcp/policy/setMcpPolicySetParamsMcpPolicySetResponseEnable/disable a server or implicit invocation.
mcp/server/restartMcpServerRestartParamsMcpServerRestartResponseRestart one server runtime.
mcp/uninstallMcpUninstallParamsMcpUninstallResponseRemove one server installation.
mcp/server/detailsMcpServerDetailsParamsMcpServerDetailsResponseLoad catalog, health, audit, and recent binding details.

​
Listing Servers

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "mcp/list",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}
Response shape: 
{
  "snapshot_version": 7,
  "generated_at": 1777900000,
  "servers": [
    {
      "id": "mcp_000000000000000001",
      "name": "filesystem",
      "display_name": "Filesystem",
      "scope": "workspace",
      "source_kind": "config",
      "transport": {
        "kind": "stdio",
        "command": "npx"
      },
      "policy": {
        "enabled": true,
        "allow_implicit_invocation": false
      },
      "required": false,
      "fingerprint": "sha256:...",
      "runtime": {
        "state": "ready",
        "live": true,
        "last_seen_at": 1777900000
      },
      "tools_count": 4,
      "resources_count": 0,
      "resource_templates_count": 0,
      "prompts_count": 0,
      "status": "ready"
    }
  ]
}
Use snapshot_version together with mcp/changed and server status notifications to keep a client catalog fresh.

​
Installing Servers

mcp/install accepts the same JSON shape users commonly put in MCP client config files: an object with mcpServers. Pass that JSON as a string in config_json. 
{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "mcp/install",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "scope_kind": "workspace",
    "config_json": "{ \"mcpServers\": { \"filesystem\": { \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/alexander/Code\"], \"env\": {} } } }"
  }
}
The JSON inside config_json is parsed by the gateway. For HTTP servers, use a URL transport entry in that config string: 
{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ..."
      }
    }
  }
}
scope_kind defaults to workspace. enabled and allow_implicit_invocation are also accepted top-level install params. enabled defaults to true; allow_implicit_invocation defaults to false. They are Pioneer policy values, not part of the MCP server config JSON itself. Secret values from env, headers, tokens, and authorization fields are stored in the gateway keystore. Protocol responses use redacted transport/source data and secret refs; they do not echo raw secret values.

​
Install Result

{
  "status": "ok",
  "servers": [
    {
      "name": "filesystem",
      "status": "installed",
      "diagnostics": [],
      "server": {
        "id": "mcp_000000000000000001",
        "name": "filesystem",
        "scope": "workspace",
        "source_kind": "config",
        "transport": {
          "kind": "stdio",
          "command": "npx"
        },
        "policy": {
          "enabled": true,
          "allow_implicit_invocation": false
        },
        "required": false,
        "fingerprint": "sha256:...",
        "runtime": {
          "state": "starting",
          "live": false
        },
        "tools_count": 0,
        "resources_count": 0,
        "resource_templates_count": 0,
        "prompts_count": 0,
        "status": "not_started"
      }
    }
  ],
  "audit": {
    "events_written": 1
  }
}
status can be ok, partial, or validation_error. Individual server result status can be installed, updated, or validation_error. Clients should render per-server diagnostics, because a config file may contain several servers and only some may fail.

​
Policy

MCP server policy mirrors skills policy:
FieldMeaning
enabledWhether the server is available to agents. Disabled servers remain installed.
allow_implicit_invocationWhether the gateway may expose the server’s tools for automatic agent use.
{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "mcp/policy/set",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "name": "filesystem",
    "scope_kind": "workspace",
    "enabled": true,
    "allow_implicit_invocation": false
  }
}
Omit enabled or allow_implicit_invocation to preserve the current value.

​
Explicit Turn Selection

An MCP server can remain not implicit and still be used in one turn through turn/start.capabilities: 
{
  "id": "cap_resend",
  "label": "resend",
  "kind": {
    "type": "mcpServer",
    "name": "resend",
    "scopeKind": "workspace"
  }
}
or for one raw tool: 
{
  "id": "cap_resend_send_email",
  "label": "resend / Send Email",
  "kind": {
    "type": "mcpTool",
    "serverName": "resend",
    "rawToolName": "send_email",
    "scopeKind": "workspace"
  }
}
Explicit MCP capabilities are materialized as provider tools for that turn only. They are audited through accepted/rejected capability diagnostics and MCP binding records; they are not injected into prompt text.

​
Runtime And Restart

runtime.state reports process/service state. Known states are not_started, disabled, starting, ready, degraded, auth_required, failed, stopping, stopped, and restarting. Restart a server when credentials, environment, or external dependencies changed: 
{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "mcp/server/restart",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "name": "filesystem",
    "scope_kind": "workspace"
  }
}
The response means the restart was accepted. Watch mcp/server/status_changed for the actual runtime transition.

​
Server Details

Use mcp/server/details for a detail panel, debug page, or agent-tool picker. 
{
  "jsonrpc": "2.0",
  "id": "eeeeeeeeeeeeeeeeeeeee",
  "method": "mcp/server/details",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "server_id": "mcp_000000000000000001"
  }
}
The response includes:
FieldMeaning
serverThe same summary object returned by mcp/list.
catalog.toolsTool names, titles, descriptions, input schema summaries, and MCP annotations.
catalog.resourcesStatic resources exposed by the server.
catalog.resource_templatesParameterized resource templates.
catalog.promptsMCP prompts exposed by the server.
healthRuntime state, status reason, last error, retry info, catalog version, and stderr tail.
auditRecent policy/tool decisions.
recent_bindingsRecent gateway callable names bound to raw MCP tool names.
MCP tool names are normalized into gateway callable names when exposed to agents. Use recent_bindings and catalog data when building debug UI.

​
Uninstalling

{
  "jsonrpc": "2.0",
  "id": "fffffffffffffffffffff",
  "method": "mcp/uninstall",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "name": "filesystem",
    "scope_kind": "workspace"
  }
}
Uninstalling removes the server installation and writes audit events. It does not rewrite past turn history; old tool calls remain part of historical turns.

​
Notifications

EventMeaning
mcp/changedServer installation or policy changed; refresh mcp/list.
mcp/server/status_changedA server runtime changed state or status.
mcp/server/catalog_changedServer tools/resources/prompts changed; refresh details or list.
For clients, these notifications are invalidation signals. The gateway remains the source of truth for current server state.