Call Tools on the MCP Endpoint

The Model Gateway publishes the RAG and MCP tools your API key may use at /mcp/. Any MCP client can list them and call them. The gateway checks your permissions, runs the tool, and returns the result.

Set API_BASE_URL and API_KEY as in Use Model Gateway tools with the Responses API, and use tools/list to get the exact tool names.

Call a tool

Send one tools/call request with the tool name from tools/list and its arguments:

curl -fsS -X POST "${API_BASE_URL}/mcp/" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "YOUR_RAG__search_documents",
      "arguments": {
        "query": "What are the main conclusions?"
      }
    }
  }'

Call a tool that needs a user sign-in

Some MCP tools belong to an external service that each user signs in to. To call one of these tools, send that user's access token with the request. Obtain the token through the external service's OAuth authorization flow; the gateway does not issue or refresh it. Put the token in params._meta.mcp_authorizations, under the name of the MCP server. The server name is the part of the tool name before the two underscores, so github__search belongs to the server github.

curl -fsS -X POST "${API_BASE_URL}/mcp/" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "github__search",
      "arguments": {
        "query": "release notes"
      },
      "_meta": {
        "mcp_authorizations": {
          "github": {
            "access_token": "YOUR_ACCESS_TOKEN"
          }
        }
      }
    }
  }'

Only bearer tokens are accepted. Send the raw access token; the gateway adds the Bearer scheme upstream. tools/list takes the same field, so send it during discovery as well to see the tools of a server the user has signed in to.

When the tool asks for authorization

The direct /mcp/ endpoint only publishes an OAuth-backed server when its token is present and accepted. If the token is missing, uses an unsupported type, or is refused by the external service, the server is omitted from tools/list and its tools cannot be called.

The shared dispatcher returns this error payload for tool-calling flows such as the Responses API when an OAuth-backed tool cannot run:

{
  "error": {
    "type": "mcp_auth_required",
    "code": "mcp_auth_required",
    "message": "MCP server requires OAuth authorization",
    "server": "github",
    "auth_type": "oauth_authorization_code",
    "reason": "missing_token",
    "metadata_rpc": "GetExternalMcpServerOAuthMetadata"
  }
}

reason	What it means
missing_token	No access token was sent for this server.
unsupported_token_type	The token is not a bearer token.
rejected_token	The external service refused the token. Get a new token and call the tool again.

One message per request

Send a single JSON-RPC message when the request carries mcp_authorizations. A request whose body is an array of messages is refused:

HTTP 400
OAuth-authorized JSON-RPC batches are not supported

Send each message as its own request. A request that carries no mcp_authorizations is not affected.