MCP: connecting agents
Facet is a Model Context Protocol (MCP) server. An external agent signs in
under one pinned role and works on documents as that role. Facet is the
resource server: it validates tokens minted by its own /OAuth/* endpoints
and issues none itself.
For agents:
POST /Api/_mcp/<role_slug>— JSON-RPC 2.0, withAuthorization: Bearer <token>. Take the URL verbatim fromGET /Api/_mcp/endpoints; never derive it from your own origin. A first call without a token answers401plus aWWW-Authenticatechallenge naming/.well-known/oauth-protected-resource. Connect:POST /OAuth/register→GET /OAuth/authorizewithresource=<per-role MCP identifier>androle=<qualified role id>→POST /OAuth/token(PKCE) →initialize,tools/list,tools/call. Bare role names answer400 invalid_request; useiam.Roles.admin, neveradmin.
When to use this
Section titled “When to use this”Connect an external agent over MCP when:
- You drive Facet from an external agent through MCP.
- You want role RBAC without an app registration.
- You need the audit to show one pinned role per session.
Before you start
Section titled “Before you start”- The account holds the role, and the role’s
connectivitylists themcpchannel. - MCP is not an app: no registration document, no grant ceiling. The role is the only bound.
- You need the endpoint URL.
GET /Api/_mcp/endpoints(browser session, app token, or API key) answers with one URL per held role, sorted by role id:
{ "endpoints": [ { "role": "iam.Roles.editor", "url": "https://facet.example.com/Api/_mcp/iam.Roles.editor" } ]}- Render the URL verbatim. The token’s
audmust equal it exactly; a URL derived from your own origin fails.
The connect sequence:
1. Discover the authorization server
Section titled “1. Discover the authorization server”A first call without a token answers 401. The WWW-Authenticate header
carries a resource_metadata address. Fetch that RFC 9728 protected resource
metadata (PRM): the per-role identifier in resource, Facet in
authorization_servers, and "bearer_methods_supported": ["header"].
2. Register the client
Section titled “2. Register the client”POST /OAuth/register implements RFC 7591 dynamic client registration. It is
stateless: Facet mints an opaque public-client id and keeps no record. The
consent screen and PKCE carry the security.
curl -sX POST https://facet.example.com/OAuth/register \ -H "Content-Type: application/json" \ -d '{"redirect_uris":["http://localhost:8765/callback"],"client_name":"my-agent"}'The answer carries the client_id — an opaque public-client id, no secret.
3. Authorize with the resource parameter
Section titled “3. Authorize with the resource parameter”Send the account’s browser to GET /OAuth/authorize. Carry the PKCE
parameters from User login, plus:
| Parameter | Value |
|---|---|
resource |
the per-role MCP identifier: https://<host>/Api/_mcp/<role_slug> |
role |
the qualified role id, for example iam.Roles.editor |
The consent screen pins that role. It denies a role the account does not
hold, and a role whose connectivity lacks the mcp channel. Both denials
carry the same access_denied answer; the code records the resource and the
role.
4. Exchange the code
Section titled “4. Exchange the code”Exchange the code at POST /OAuth/token as the login flow does. The access
token carries aud (the per-role identifier, exact match), role (the
qualified id), sub (the account id), sid (the session id), and no app
claim.
5. Call the tool surface
Section titled “5. Call the tool surface”JSON-RPC 2.0 rides POST /Api/_mcp/<role_slug>. One request carries one
call; the answer is one response. Start with initialize; the server answers
with its protocol version and the pinned role. Then send
notifications/initialized — it expects no response. List the role’s tools:
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list"}The answer lists the tools with name, description, and inputSchema —
see Agent tools for the catalogue. Call one:
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_documents", "arguments": { "domain": "crm", "doctype": "Contact", "filters": { "status__eq": "active" }, "sort": ["-created_at"] } }}6. Refresh the session
Section titled “6. Refresh the session”POST grant_type=refresh_token to /OAuth/token. An MCP session revalidates
the account, the held role, and the role’s mcp channel. A role that lost
the channel loses its sessions at the next refresh; a live access token
stays valid to its TTL.
Explanation
Section titled “Explanation”The model
Section titled “The model”- The URL pins the role. One
:role_slugserves one session. There is no in-session switch; another role means another URL. - Role ids are qualified. The
roleparameter and the URL slug carryiam.Roles.admin; bare names are ambiguous across domains. - MCP is not an app. No grant intersection applies; plain role RBAC runs, exactly as on REST.
- No system principal. The dispatch rejects a system context outright.
- MCP is a data plane. Tools work on documents of registered doctypes; schema authoring stays on REST and in the builder assistant.
Limits
Section titled “Limits”The optional mcp: block in config.{env}.yml sets the caps:
| Key | Default | Bounds |
|---|---|---|
max_concurrency_per_sid |
4 | dispatches in flight per session; over the cap, requests wait |
max_result_rows |
200 | rows a list tool returns |
max_response_bytes |
1048576 | bytes of a tool result envelope |
max_batch_ops |
25 | operations in one batch call |
Query duration rides the shared statement timeout
(database.statement_timeout_ms); there is no separate MCP pool. Files never
ride JSON-RPC: request_artifact_upload mints a one-time signed upload URL —
see Agent tools and Uploading and serving files.
Attribution
Section titled “Attribution”Every write stamps mutations.channel = "mcp" plus the pinned role as
acting_role. The audit shows the session’s one role — see Auditing activity.
Example
Section titled “Example”After consent, exchange the code and call the surface. Build the PKCE pair as User login shows:
curl -sX POST https://facet.example.com/OAuth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&redirect_uri=http://localhost:8765/callback&code_verifier=VERIFIER"
curl -sX POST "https://facet.example.com/Api/_mcp/iam.Roles.editor" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'Troubleshooting
Section titled “Troubleshooting”The first call answers 401 with a WWW-Authenticate challenge.
That answer is normal. Follow resource_metadata to the PRM document and
start the flow.
400 invalid_request names the role shape.
The authorize role parameter carries a bare name. Send the qualified id:
iam.Roles.admin, not admin.
The consent screen denies the sign-in.
The account does not hold the role, or its connectivity lacks the mcp
channel. Both denials carry access_denied.
The token works on MCP, and REST refuses it.
By design. The token’s aud names the MCP surface; REST rejects it, and so
does the endpoints directory. Use a session, an app token, or an API key.
A response carries the MCP-Tools-Changed header.
The role’s permissions changed. Call tools/list again before the next call.
Related
Section titled “Related”- Agent tools — the catalogue these routes serve.
- How apps work on Facet — the app model; MCP is not an app.
- Governing the assistant — mounts the same catalogue.
- AI under the caller’s rights — the rights model.
- Internals on GitHub: mcp.md.