Run it

HTTP login and users

No token, no harbour. Every request shows its papers.

In short

  • fyrr reader serve can serve many users over Streamable HTTP at /mcp; each request carries the user's OIDC access token.
  • With Keycloak it takes two Keycloak objects, about ten configuration keys, a writer that pulls the users and a reader behind a TLS proxy.
  • The reference at the end lists the exact token rules and limits, also for identity providers other than Keycloak.

What you get

The rules behind it (subjects, reader tokens, the canonical directory) are in the security model.

1. Prepare Keycloak

In the realm your users sign in to, create two objects:

  1. A directory client, fyrr-directory. A confidential OpenID Connect client with Client authentication on and Service accounts roles enabled (no other flows). Under Service account roles, assign the view-users role of the realm-management client. Copy its client secret from Credentials.
  2. A client scope, fyrr:read. OpenID Connect, Include in token scope on. Under Mappers, add an Audience mapper with Included Custom Audience fyrr and Add to access token on. Then open the client your users sign in with (the one their MCP client uses) and add fyrr:read under Client scopes as a Default scope. Its access tokens then carry fyrr in aud and fyrr:read in scope; other audiences, such as account, may stay.

Users need an e-mail address that Keycloak marks as verified, in one of your corporate domains.

2. Configure fyrr

Add these keys to the configuration file:

[identity]
hashing_key = { env = "FYRR_IDENTITY_KEY" }        # the same on every host
encryption_key = { env = "FYRR_ENCRYPTION_KEY" }   # 64 hexadecimal characters

[identity.directory]
provider = "keycloak"
endpoint = "https://sso.example.com"
realm = "acme"
client_id = "fyrr-directory"
credentials = { env = "FYRR_DIRECTORY_CLIENT_SECRET" }
verified_domains = ["example.com"]

[identity.oidc]
audience = "fyrr"

[reader.http]
listen = "127.0.0.1:8080"
public_url = "https://fyrr.example.com/mcp"

Nothing else is needed: the token issuer defaults to the realm (https://sso.example.com/realms/acme), the Keycloak token profile is on and the keys come from the realm's protocol/openid-connect/certs, all from this file, never from a token. Then check the file:

fyrr config check
fyrr config show | grep identity.oidc    # the derived issuer and key URL

3. Start the writer and the reader

fyrr writer namespace create      # once
fyrr writer serve                 # keeps running: sources and the directory on schedule

writer serve pulls the directory every identity.directory.sync_interval (15 minutes) and publishes changes by the next successful pull and commit; a membership change made during a pull may wait for the following pull. Scheduling shows the cron alternative. Every enabled user with a verified e-mail in verified_domains becomes a canonical user.

Start the reader on the reader host, behind a TLS-terminating proxy that keeps the public Host header:

fyrr reader serve                 # plain HTTP on reader.http.listen
server {
    listen 443 ssl;
    server_name fyrr.example.com;
    # ssl_certificate and ssl_certificate_key as usual
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_read_timeout 310s;
    }
}

Clients must not reach the listener directly.

4. Grant access

Each canonical user holds the reader token usr:<lower-cased e-mail> and grp:keycloak:<group ID> for each Keycloak group they belong to (the group ID is the UUID in the group's Keycloak URL). List them in a fixed source:

[[sources]]
id = "handbook"
type = "local-files"
permissions = "fixed"
readers = ["grp:keycloak:11111111-2222-3333-4444-555555555555", "usr:ada@example.com"]
[sources.scope]
paths = ["/srv/handbook"]

permissions = "sync" sources link their accounts to canonical users by verified corporate e-mail: Google Drive (its Workspace domain), Slack and Jira do this without extra work (Slack and Jira use verified_domains unless their corporate_domains is set). Notion and local files are always fixed. GitHub reports no usable e-mail, so its accounts need explicit links in a directory snapshot; with HTTP users, use GitHub with permissions = "fixed".

5. Connect an MCP client

Point the client at https://fyrr.example.com/mcp. Clients that discover OAuth settings read the issuer and scope from /.well-known/oauth-protected-resource; a 401 carries the same pointer in WWW-Authenticate. To check by hand with a user's access token:

curl https://fyrr.example.com/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"backup"}}}'

6. Troubleshooting

SymptomCause and fix
401 unauthorizedThe token failed a token rule: usually the audience (fyrr:read is not a default scope of the sign-in client, or its Audience mapper does not add fyrr to the access token), an expired token, or a token from another realm. Decode it and compare iss, aud, scope and typ.
503 authorization_unavailableThe token is valid but its subject is not bound: the user is not yet in a published directory pull, is disabled, or has no verified e-mail in verified_domains. It also means the last directory pull is older than identity.validity_deadline, or the keys could not be fetched. Check fyrr writer status.
A user is missing although the e-mail looks rightKeycloak does not mark it verified. Users federated from LDAP need Trust Email on the LDAP provider, or a verified flag set by an administrator.
403 host_mismatchThe proxy does not pass the public Host: set proxy_set_header Host $host. The reader logs http refused code=host_mismatch.
403 invalid_argumentThe request had an Origin header: browsers cannot call /mcp directly.
config check reports identity.oidc.issuerThe configured issuer differs from the directory's; leave issuer out to take the directory's.

Reference

Tokens

A request is served only when every rule holds. Invalid tokens receive 401 unauthorized with a WWW-Authenticate header; unavailable keys or subject bindings return 503 authorization_unavailable.

Keys

The JWKS document may hold at most 16 keys with distinct kids in at most 256 KiB; usable keys are RSA with 2048–4096-bit moduli and exponent 65537. It is fetched without redirects within 3 seconds, at most every jwks_refresh_interval (5 s, also on an unknown kid), and trusted for jwks_validity (5 minutes); after that, without a successful fetch, requests get 503 authorization_unavailable.

HTTP boundary

Other directories

Use a SCIM or snapshot directory to bind subjects when not using Keycloak.

The writer's administration listener serves /admin/status and the SCIM endpoints with two separate credentials; a non-loopback listener requires TLS termination in front of it, declared with tls_terminated = true. All keys are in identity and reader settings.

A signing key withdrawn by the identity provider remains trusted for up to jwks_validity after the last successful JWKS fetch. Stale keys fail closed when refresh fails. Unknown key IDs trigger at most one refresh attempt per jwks_refresh_interval; an in-flight refresh does not block current keys.

Edit this page on GitHub ↗