Skip to content

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, with Authorization: Bearer <token>. Take the URL verbatim from GET /Api/_mcp/endpoints; never derive it from your own origin. A first call without a token answers 401 plus a WWW-Authenticate challenge naming /.well-known/oauth-protected-resource. Connect: POST /OAuth/register → GET /OAuth/authorize with resource=<per-role MCP identifier> and role=<qualified role id> → POST /OAuth/token (PKCE) → initialize, tools/list, tools/call. Bare role names answer 400 invalid_request; use iam.Roles.admin, never admin.

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.
  • The account holds the role, and the role’s connectivity lists the mcp channel.
  • 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 aud must equal it exactly; a URL derived from your own origin fails.

The connect sequence:

Diagram Diagram

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"].

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.

Terminal window
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.

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.

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.

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"]
}
}
}

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.

  • The URL pins the role. One :role_slug serves one session. There is no in-session switch; another role means another URL.
  • Role ids are qualified. The role parameter and the URL slug carry iam.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.

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.

Every write stamps mutations.channel = "mcp" plus the pinned role as acting_role. The audit shows the session’s one role — see Auditing activity.

After consent, exchange the code and call the surface. Build the PKCE pair as User login shows:

Terminal window
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"}'

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.