MCP authentication

Last updated Jun 14, 2026

The Matter MCP server authenticates every connection with a Bearer credential. Two ways to get one: the browser sign-in your MCP client offers (no key handling), or an API key from your dashboard.

Browser sign-in (OAuth 2.1)

Connect with no key and clients that implement MCP authorization discover the login flow automatically:

1. The server answers the first unauthenticated request with 401 and a WWW-Authenticate header pointing at its protected-resource metadata (/.well-known/oauth-protected-resource).
2. The client reads the authorization server from that document, registers itself (dynamic client registration), and opens your browser at the Matter sign-in.
3. You sign in, pick an environment — test is preselected; sandbox and live are explicit choices, and live requires an additional confirmation — and approve the connection.
4. The client exchanges the authorization code (PKCE) for a 24-hour access token plus a rotating refresh token, and renews silently from then on.

The token is a real Matter credential (prefix sk_mcp_…) scoped to the environment you chose, with execute-tier (3) capability — tier-4 autonomous tools stay behind manually minted keys. Every connection is listed under Settings -> API keys -> MCP connections; disconnecting revokes the token and its refresh chain immediately.

Bearer key

Any Matter key or scoped token works as a Bearer credential — for interactive runtimes (Claude Code, Claude Desktop, Cursor, Windsurf, Zed) and headless ones (CI pipelines, server-side agents) alike:

Authorization: Bearer sk_test_matter_example_...
Authorization: Bearer tok_4Kj2m8pQ...

Keys come from your dashboard: Settings -> API keys — use your saved test key, or rotate-and-reveal a fresh one (rotation mints a new key and revokes the previous one). Put the key in your MCP client configuration, never in the conversation. See installation for per-client configuration.

Scoped tok_* tokens map to the structured scope policy — e.g., entities.read, filings.write, tokens.manage. See authoring scope policies for worked examples per tier.

Manual keys are the path for headless runtimes and for autonomous tier-4 agents — the browser sign-in above caps at tier 3 by design.

Tier-filtered tool visibility

On connection, the MCP server:

1. Parses the Bearer token from the Authorization header.
2. Resolves the token's tier. Secret-key shapes (sk_test_…, sk_live_…, sk_sandbox_…, dashboard-minted sk_dashboard_…, OAuth-minted sk_mcp_…) classify through the canonical prefix registry — the same one the API server resolves, so the two layers cannot drift. Scoped tok_* tokens resolve their tier and policy through the API (self-resolution is pending; tok_* minting ships with it).
3. Filters the generated tool catalog — tools above the token's tier, or outside the scope policy, are not returned by list_tools.
4. Re-checks authorization on every call_tool (defense-in-depth) — the API server is the authoritative enforcer either way.

Example — a tier-1 pk_live_… key sees only read-only tools:

matter_retrieve_entity
matter_list_entities
matter_retrieve_cap_table
matter_list_filings
matter_retrieve_filing
matter_retrieve_document
matter_list_documents
matter_retrieve_compliance
matter_list_compliance_deadlines
matter_list_events
matter_retrieve_event
matter_subscribe_to_events
matter_retrieve_audit
matter_retrieve_request
... (all read-only tools allowed by the token's policy)

A tier-4 tok_… with a scope allowing entities.* and filings.create for Delaware only sees the full read-only catalog plus matter_create_entity, every filing creation tool (with conditions.jurisdiction: ["US-DE"]), and nothing else.

Dual attribution via Matter-Agent-Id

When an agent runtime invokes the MCP server, it should propagate the agent's identity via Matter-Agent-Id: agt_…. The MCP server forwards this to the Matter API, producing the authorized_by envelope on every resulting Event and AuditEntry:

{
  "authorized_by": {
    "human_principal_id": "usr_4Kj2m8pQ",
    "agent_id": "agt_Nq3KcAbc"
  }
}

Without dual attribution, agent-initiated actions wash through as "the platform did this" — Matter's audit trail requires the agent to be identifiable separately from its human principal.

Token rotation

Revoke a compromised or retired token:

matter_revoke_token({ "token_id": "tok_..." })

(Or POST /v1/tokens/{id}/revoke directly.) Active MCP connections using the token are terminated within 60 seconds.