Connect an MCP client

Your agents reach your systems through a Gateway, which speaks the Model Context Protocol (MCP). This page shows how to point an MCP client at a Gateway, with Claude Code, with other clients, and with plain HTTP requests.

This page is about your organization's own agents, which use agent tokens. If your customers bring their own agents, they sign in instead: see What your customers see.

What an agent needs#

The older header name X-AgentGov-On-Behalf-Of still works, but the Gateway logs a warning each time it's used, so rename it in existing configurations.

Every call the agent makes counts as a request by that person. The person and the agent's owner can't approve the agent's requests, so someone else has to (see Approvals).

The agent only sees the tools your policy could let it run. If it lists no business tools at all, see Calling tools.

Claude Code#

Keep the agent's token out of your code repositories. Use a separate folder for the agent, and read the token into a shell variable so it doesn't end up in your shell history:

mkdir -p ~/purchasing-agent && cd ~/purchasing-agent
read -rs "TOKEN?Agent token: "; echo     # zsh; in bash use: read -rsp "Agent token: " TOKEN; echo
claude mcp add --scope project --transport http erp https://<your-gateway>/mcp \
  --header "Authorization: Bearer $TOKEN" \
  --header "X-Gatelion-On-Behalf-Of: <user id>"
unset TOKEN
chmod 600 .mcp.json

--scope project writes the server, including the token, to .mcp.json in that folder. Never commit that file, and delete it when you revoke the token.

Then start Claude Code from a terminal, in that folder:

The first time, use a terminal rather than an editor panel: some editor integrations don't show these trust prompts, and the server then stays waiting for approval. Once the folder is trusted, the panel works too.

Other MCP clients#

Any MCP client can connect if it supports:

• the Streamable HTTP transport, and
• custom request headers, so it can send Authorization and X-Gatelion-On-Behalf-Of.

Clients that can only sign in with OAuth, and can't send their own headers, can't connect as your own agents. They can connect to a Gateway set up for customer access, where people sign in with your customers' login: see Your customers' agents.

Without an MCP client#

The Gateway speaks JSON-RPC over HTTP, so you can call it with curl or any HTTP library. Every request is a POST to the MCP address with these headers:

1. Initialize. Ask for a protocol version; the answer says which one the Gateway uses. The Gateway supports MCP protocol versions up to 2026-07-28. These examples ask for 2025-06-18, which it also supports, so it answers with that one.

curl -sS https://<your-gateway>/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Gatelion-On-Behalf-Of: <user id>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

2. List the tools. Send the version from step 1 from now on.

curl -sS https://<your-gateway>/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Gatelion-On-Behalf-Of: <user id>" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

3. Call a tool.

curl -sS https://<your-gateway>/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Gatelion-On-Behalf-Of: <user id>" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"erp.inventory.list","arguments":{}}}'

The answer may come as plain JSON or as server-sent events. With server-sent events, the JSON-RPC message is on the last line that starts with data::

event: message
data: {"result":{"content":[{"type":"text","text":"{\"status\":\"succeeded\",…}"}],"structuredContent":{"status":"succeeded",…},"isError":false},"id":3,"jsonrpc":"2.0"}

What the result means is explained in Calling tools.

If the connection fails#

Related: Agents and tokens · Calling tools · Handling errors

Still stuck? Contact support from the console.