Skip to manual
gluon

API and integrations

Connect an MCP client

Offer an AI client the tools and resources a person may use, over OAuth.

Integration administrator and tool developer

Gluon's MCP server lives at https://gluon.example/api/mcp. It speaks JSON-RPC over streamable HTTP with plain JSON responses and negotiates protocol versions 2025-11-25, 2025-06-18 and 2025-03-26. Calls go through the same policy engine and retrieval as chat and the REST API, with context.channel set to mcp. A policy that lists only chat, apps and api therefore allows a read in chat and withholds the same read over MCP.

Connect a client

  1. Have an administrator approve the client with the Capabilities it needs (see Approve OAuth clients and handle rate limits). A client that publishes a Client ID Metadata Document, such as Visual Studio Code, is approved by its metadata URL.
  2. Point the client at https://gluon.example/api/mcp. Its first request without a token gets 401 with WWW-Authenticate: Bearer resource_metadata="https://gluon.example/.well-known/oauth-protected-resource/api/mcp", which a compliant client follows to start the sign-in.
  3. The person signs in to Gluon in their browser. The client receives a token bound to the MCP resource and to that person, and uses it on every call.

What the client is offered

tools/list returns:

  • ask: a cited question over what the person may see (autonomy L0, risk tier A). It takes mode, fast or accurate: fast runs one search, accurate searches further and takes longer. Without it, the Capability's default applies, else fast. A Capability that pins a mode refuses the other one.
  • record_outcome: the task an answer helped with is done. Pass the answer's requestId (one of the person's own answers), or the capability the work was for with your own taskId. An answer, or a task, counts once. Gluon's Drift report counts these as verified completions for time saved; the REST equivalent is POST /api/outcomes.
  • get_<type> and search_<type> for every object type the bound Capability reads, for example get_procurement_contract and search_procurement_contract. get_ takes id; search_ takes query and limit (default 20).
  • One tool per action and function exposed on mcp. Its description states the effective autonomy level and risk tier.

resources/list returns the views exposed on mcp as gluon://views/<name>; read one with resources/read.

A withheld element is listed and refuses when called. Anything outside the person's segments is absent from the tools, the resources and every count. Each tool takes an optional capability argument; leave it out when the client has one approved Capability offered to the person.

Call a tool

Shell
curl -s https://gluon.example/api/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_party_supplier","arguments":{"query":"ACME"}}}'

A result carries text content and structuredContent. A refused call is still a tool result, with isError: true and structuredContent such as {"refused": "policy", "status": 403, "detail": "party.Supplier is withheld (policy)"}, so the model can tell the person why. A refused resources/read is a JSON-RPC error instead: -32001 when withheld, -32002 when absent.

An action tool needs the execute scope and goes through the same pipeline as the REST API. It answers pending-approval with an approvalUrl when an approver must sign off, and calling it again with the same parameters returns the same run.

Transport rules

  • GET /api/mcp answers 405, since the server sends no stream of its own.
  • A request whose Origin differs from Gluon's own is refused with 403, which also keeps browser-based clients on other origins out for now.
  • An MCP-Protocol-Version header naming another version is refused with 400.
  • Malformed params get -32602; a body that is not a JSON-RPC object gets -32600.
  • A context sent in tool arguments is dropped and audited as api.client-context-ignored.

Rate limits and revocation work as on the REST API: 429 with Retry-After past the client's limit, and a revoked client, grant or person fails on the next request. While ask composes an answer, Gluon re-checks the token and the person's access at every chunk.

Terminal showing tools/list output with ask, get_party_employee, search_party_supplier and more tool names.
tools/list for one person: ask and record_outcome, then a get and a search tool per readable type.
Terminal showing search_party_supplier and search_procurement_contract both answering refused policy, status 403.
Two tool calls refused as withheld by policy, returned as tool results with status 403.