attesto_mcp_server

# attesto_mcp_server

`attesto_mcp_server` is an Apache-2.0, Attesto-native MCP server for Elixir.
It provides one protocol core with preferred MCP `2026-07-28` behavior and
negotiated `2025-11-25`/`2025-06-18` compatibility, a protected
Plug-compatible Streamable HTTP boundary, and a line-oriented stdio adapter.

Protected HTTP traffic enters the approved
`AttestoMCP.Plug.ProtectResource` boundary before body decoding and protocol
dispatch, with route-derived scopes applied through its prepared dynamic
authorization API. The required `attesto_mcp ~> 1.2.1` dependency provides
`ProtectResource.prepare/1`, `authenticate/2`, and `authorize/3`; no older
authentication fallback is included. Configure the canonical resource
path/origin, Attesto verifier, principal policy, replay and certificate
callbacks, and least-privilege scopes in the host application. The package does
not contain an OAuth authorization server or token issuer.

## Quick start

```elixir
{:ok, server} = AttestoMCP.Server.start_link(name: :demo)

:ok = AttestoMCP.Server.register_tool(server, "hello", %{
  description: "Say hello",
  input_schema: %{"type" => "object"},
  handler: fn %{"name" => name}, _auth -> {:ok, "Hello #{name}!"} end
})

plug AttestoMCP.Server.Plug,
  server: server,
  path: "/mcp",
  scopes_supported: ["workspace.mcp"],
  default_scopes: ["workspace.mcp"],
  auth: [
    config: &MyApp.Attesto.config/0,
    resource: "/mcp",
    base_url: "https://mcp.example.com"
  ]
```

`AttestoMCP.Server.API` is the stable documented facade for these startup,
registration, dispatch, session, subscription, and cancellation calls; the
lower-level `AttestoMCP.Server` module remains available for transport hosts.

Handler inputs are primitive-specific. Tools receive their JSON arguments map;
prompts receive `%{name: name, arguments: arguments}`; resources receive
`%{uri: uri, params: template_params}`; and completions receive
`%{ref: ref, argument: argument, value: value, context: completion_context}`.
Declared envelope fields use atom keys while nested MCP values keep their JSON
string keys; resource MRTR retries additionally carry string-keyed response
entries at the top level. An arity-2 handler's second argument is the
authenticated request context; arity-1 and MFA forms are also supported.

`scopes_supported` controls the public RFC 9728 document for that mount, while
`default_scopes` controls protected operations without a non-empty
method-specific `scope_map` entry. Keep the two aligned with grants actually
issued by the Attesto authorization server. If an AttestoPhoenix router owns
the metadata route via `--reuse-metadata-route`, configure its protected
resource metadata there; the MCP Plug cannot alter a route it does not serve.

An optional `context_builder` function or MFA receives the authenticated
`Plug.Conn` and contributes a map under `context.host_context`; it cannot
replace the package-owned principal, scopes, claims, sender, or tenant fields.
Return `{:error, AttestoMCP.Server.Result.error(message, code)}` for bounded
business failures that are safe for a client. Other failure values and
exceptions remain generic at the protocol boundary.

### Phoenix installer

Phoenix hosts can install the same boundary with the optional Igniter task:

```sh
mix igniter.install attesto_mcp_server --base-url https://mcp.example.com
```

When the host already depends on `attesto_phoenix`, the generated routes derive
the verifier and protected-resource callbacks from that package's validated
OTP configuration on each applicable request. This carries access-token JTI
revocation, principal loading, DPoP replay/nonce, canonical-request, and mTLS
certificate policy into the MCP boundary without freezing callback closures at
router compile time. The installer preserves its native `localhost` callback
compatibility default, but the installer does not enable Client ID Metadata
Documents (CIMD) by default, so an established host cannot accidentally select
an Ecto-backed cache before running its `attesto_client_id_metadata` migration. Pass
`--enable-cimd` only after verifying that storage; this adds the Req dependency
used by the default fetcher. Existing host values win, including cache, repo,
table-prefix, allowlist, and disabled settings.

Automatic AttestoPhoenix integration requires every authenticated token
subject to resolve through the host's `load_principal` callback. A revoked JTI,
an unresolved subject, or a callback failure denies the MCP request with a
neutral invalid-token response. Return a principal term whose equality is
stable for the same identity: the server uses it for request ownership,
session and subscription isolation, and rate/concurrency accounting.

This path supports direct public-Hex `attesto_phoenix` requirements that
overlap `>= 2.14.1 and < 3.0.0` and Req requirements that overlap
`>= 0.6.1 and < 1.0.0`; existing stable requirements are narrowed to their
intersection. That intersection must contain at least one stable release;
pre-release-only matches are intentionally rejected. If the dependency catalog
or either required declaration cannot be validated safely, installation stops
before editing. The explicit-callback path does not modify dependencies. Hosts
without `attesto_phoenix` provide an application-owned callback instead:

```sh
mix igniter.install attesto_mcp_server \
  --base-url https://mcp.example.com \
  --attesto-config MyApp.Attesto.config/0
```

The idempotent installer adds a supervised MCP module, conservative runtime
configuration, a starter registration test, and distinct top-level forwards
for `/mcp` and its public RFC 9728 metadata URL. Use
`--reuse-metadata-route` to retain exactly one statically proven
`use AttestoPhoenix.Router` plus
`attesto_routes(protected_resource_paths: ["/mcp"])` metadata route and
generate only the MCP forward; ambiguous or mismatched
routes stop before editing with the manual wiring required. Otherwise the
metadata forward uses a generated application-owned wrapper, preserving
compatibility with Phoenix 1.7's one-forward-per-plug rule. A direct standard
Phoenix endpoint parser is wrapped to bypass `/mcp` and route-equivalent
trailing slashes before authentication; custom or ambiguous parser setups make
the installer stop before any edit and report the required remediation while
retaining host ownership. If the endpoint cannot be inferred or its source is
unavailable, installation proceeds with a warning and leaves manual pipeline
verification to the host. A proven simple endpoint with no parser produces an
informational warning but needs no endpoint edit. It never creates an issuer, credentials,
consent policy, token storage, or dynamic-registration policy. See
[Phoenix installation](docs/usage.md#phoenix-installation) for options and the
division of responsibilities between the packages.

Custom `--mcp-path` values must be non-root ASCII paths made from
slash-separated URI-unreserved segments (`A-Z`, `a-z`, digits, `.`, `_`, `~`,
and `-`). The task stops before editing when dependency, router, route, or
installer ownership cannot be established conservatively.

Bandit is the documented development/test adapter, while the production
library depends only on Plug. For a local loopback example, see
`examples/bandit.exs`; it uses a credential-free verifier configuration and
returns 401 until a host supplies a token. For stdio interop, run
`elixir examples/stdio.exs` or call `AttestoMCP.Server.Stdio.run/2`.

The package-owned authenticated frozen-conformance fixture and its exact
observed results are documented in [`CONFORMANCE.md`](CONFORMANCE.md). It is a development/test
fixture only; its generated Attesto credential is never part of the library
or production configuration.

## Scope defaults

Tools listing uses `AttestoMCP.Scopes.tools_read/0`; tool execution uses
`tools_call/0`; resources and prompt/completion reads use their corresponding
`AttestoMCP.Scopes` helpers. A non-empty `scope_map["completion/complete"]`
entry replaces the category default for both prompt and resource references;
an absent or empty entry cannot disable those defaults. Every HTTP request is
reauthenticated and handles or session IDs are never authorities by themselves.

### Explicit definition-scoped HTTP policy

Hosts that issue fine-grained definition scopes can opt into per-method policy
without changing the secure defaults:

```elixir
scope_policy: %{
  "tools/list" => :visible_definitions,
  "tools/call" => :selected_definition,
  "resources/list" => :visible_definitions,
  "resources/templates/list" => :visible_definitions,
  "resources/read" => :selected_definition
}
```

The visible mode filters catalogs with each definition's `required_scopes` and
`authorize` callback. The selected mode binds the requested tool, static
resource, or URI template, then checks its scopes through the prepared Attesto
boundary before retry-state consumption or handler invocation. Hidden and
denied definitions use the same neutral unknown result. This option is
explicitly opt-in; omitted policy preserves the generic method scopes, and an
empty `scope_map` entry still restores that default. A policy method may not
also appear in `scope_map`, including with an empty entry; an explicit Plug
`scope_map` replaces the server map, and the effective map is revalidated at
request time for named or restarted servers.
Definitions with `required_scopes: []` are authenticated-only only on methods
explicitly mapped to this policy; default and empty-map methods still require
their generic scope.

Subscription establishment and delivery are unchanged: opening a stream keeps
its generic category scopes, while each delivery reauthorizes the captured
principal and tenant with the matched definition scopes. `subscriptions/listen`
is intentionally not a definition-policy method.

## Operational notes

Pin the public origin behind a trusted proxy, use TLS in deployment, and keep
credentials/proofs/private content out of logs and Telemetry. Configure the
documented `max_queue`, `stream_keepalive_ms`, `stream_queue_size`, and
concurrency/timeout limits. `page_size` bounds catalog pages; `cache_ttl_ms`,
`cache_scope`, and `allow_public_cache` control cache metadata, with public
caching requiring both explicit opt-in and an authorization-independent result.
Request `_meta` values must be JSON objects when present; malformed values
produce request-local protocol errors without taking down either transport.
Published catalog notifications accept only `type` and optional object
`_meta`; resource-update notifications additionally require `uri`. Unknown
fields or malformed metadata are rejected before modern or legacy fanout.
Legacy resource subscriptions per session and modern resource filters per
subscription are fixed at 128 unique URIs and 4,096 bytes per URI; duplicates
do not consume another entry.

Use `register_all/2` or the startup `:registrations` option when a catalog must
appear atomically. A failed batch changes neither the registry nor its catalog
revision and emits no invalidation. One successful batch emits at most one
invalidation per affected catalog.

Legacy sessions use the private in-memory store by default. A durable host may
provide `session_store: {Adapter, handle}` and an explicit
`session_namespace`; the adapter implements
`AttestoMCP.Server.SessionStore`. Set `session_clustered: true` only with a
shared adapter and explicit namespace. Cluster peers then load the same session
records and fan modern, legacy, and catalog notifications to the node holding
each live stream. Live PIDs and sockets are never persisted, so clients reopen
streams after node loss; session identity, negotiated revision, capabilities,
subscriptions, and logging level survive. Store loss stops the server instead
of silently falling back to local memory when the configured store handle is a
monitored process; other adapters fail closed when an operation cannot reach
their backend. Use a globally unique `session_namespace` when unrelated
deployments share the same store or Erlang cluster. Cross-node notification
delivery is asynchronous and does not provide replay or exactly-once delivery
across a network partition.

`telemetry_metadata` adds at most 16 bounded scalar host dimensions to emitted
events without permitting reserved-key replacement. `handler_task_init` runs
inside each request worker before its handler; `exception_reporter` receives
trusted exception details while wire responses and Telemetry remain scrubbed.
All three options accept documented function/MFA forms where applicable.

Plug options override server defaults for that adapter, while its effective
`scope_map` is the single HTTP policy source.
Optional task profiles are disabled for this release; their
incomplete implementation cannot be enabled.

See [docs/usage.md](docs/usage.md) and `SECURITY.md`.