flexway
FRENTalk to an expert

MCP tools for agents

GuideDevelopersSince version 0.1.0

Markdown

On this page

An AI agent calls the API's operations as MCP tools (Streamable HTTP, sessionless), under the same decision as a REST call.

Product side: Agents: MCP and A2A; operations side: Agents and MCP.

Getting a token for the surface

A host's MCP surface (for example https://api.example.com/mcp) accepts only OAuth tokens issued for its URL (RFC 8707). Discovery is standard:

curl -i -X POST https://api.example.com/mcp      # 401, WWW-Authenticate: Bearer resource_metadata="..."
curl https://api.example.com/.well-known/oauth-protected-resource/mcp
# {"resource":"https://api.example.com/mcp","authorization_servers":["https://login.example.com"],...}

Ask that authorization server for the token with resource=https://api.example.com/mcp. A compliant MCP client does all this on its own. API keys are not accepted on the MCP surface.

Listing and calling

curl -s https://api.example.com/mcp -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -s https://api.example.com/mcp -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_order","arguments":{"id":"42"}}}'
Rule Detail
tools/list Shows only what your token may call
Result The API response's body, bounded to 1 MiB
A tool refused An isError result carrying the RFC 9457 problem, its code readable
Quota The same bucket as your REST calls
Unattended agent An agent acting for itself (the token's subject is the client) does not see the tools reserved to a person

Your token never leaves the gateway

The API behind the tool never receives your token: if it verifies one, it receives a token exchanged for it. A chain of agents acting for a person is bounded in depth and age by the operator; past it, 403.

Next steps