Connect an MCP client

The gateway speaks MCP over Streamable HTTP at one endpoint, behind one bearer token. Any MCP host works: nothing in the surface assumes a specific client or model.

Endpointhttps://<your-instance>/mcpPOST, Streamable HTTP (ADR-0010)

AuthenticationAuthorization: Bearer <principal token>your service-principal token (minted with `admin.js token create`) — not the operator token used by this console

Tool names<connector>__<operation>e.g. pipedrive__deal_list; a dot in the operation id becomes an underscore

Claude Code

Use a project .mcp.json instead of claude mcp add --header — the header there is a literal command-line argument, so the token would sit in this process's own argv and in shell history for as long as it runs. ${VAR} in .mcp.json is expanded by Claude Code at runtime, straight from the environment, and never placed on a command line. Export the token with a hidden prompt in the shell that launches claude, so it never reaches history either (zsh: read -rs "MCPU_CLIENT_TOKEN?paste the token: " instead of -rsp):

read -rsp 'paste the token: ' MCPU_CLIENT_TOKEN; echo
export MCPU_CLIENT_TOKEN

Then, in .mcp.json (project root, or your global Claude Code config):

{
  "mcpServers": {
    "mcp-universe": {
      "type": "http",
      "url": "https://<your-instance>/mcp",
      "headers": { "Authorization": "Bearer ${MCPU_CLIENT_TOKEN}" }
    }
  }
}

Generic MCP host configuration

Most hosts (Claude Desktop, Cursor, VS Code, an agent framework) take a JSON entry of this shape.

{
  "mcpServers": {
    "mcp-universe": {
      "type": "http",
      "url": "https://<your-instance>/mcp",
      "headers": { "Authorization": "Bearer <principal token>" }
    }
  }
}

Check it from a shell

Read the token in rather than typing it after Bearer — that keeps it out of shell history and off this process's own argv (ps, /proc/<pid>/cmdline); -H @- reads the header from stdin instead. In zsh, read -rsp 'prompt: ' VAR has no -p — use read -rs "VAR?prompt: " instead.

read -rsp 'paste the token: ' MCPU_CLIENT_TOKEN; echo
printf 'Authorization: Bearer %s' "$MCPU_CLIENT_TOKEN" | curl -sS https://<your-instance>/mcp \
  -H @- \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
unset MCPU_CLIENT_TOKEN

What a call returns

Every tool answers with the result envelope: outcome is success, failure or pending_approval, and nothing is ever dropped quietly — a truncated page, a redacted field or a failed audit write is a notice on the result. On this M0 surface, destructive, financial and external-effect operations, and any that require a confirmation, are refused at the tool layer with nothing sent to the target; approvals arrive with the policy engine (M1).