Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
mcp_auth_proxy
What it is
Supports agent sessions: lets external MCP clients (e.g. cursor.com)
authenticate against Macro. A library crate (mounted into agent_harness_service, not
its own binary) implementing an OAuth 2.1 Dynamic Client Registration broker
in front of FusionAuth, which doesn't support DCR itself.
Start here
README.md: the security model — which redirect URIs are usable, and which client a grant belongs to. Read before touching/register,/authorize, or/tokenlogic, and its "Disconnecting a client" section before touching/revoke.src/domain/service.rs+src/domain/service/test.rs: the broker's core logic (registration, authorize, token/refresh).src/domain/redirect_uri.rs: the redirect URI policy from the README: trusted, needs consent, or refused.src/domain/browser_binding.rs: the cookie secret tying a flow to the browser that started it, and the anti-forgery token the broker's forms carry.templates/: the broker's pages (sign-in chooser, consent and its cancellation, email sign-in, manual delivery), which sharebroker_page.css.src/domain/ports.rs:ClientRegistrationStore,OAuthProvider,EmailCodeProvider,RefreshTokenBindingStore— the ports the service depends on.src/inbound/axum_router.rs: HTTP routes;src/inbound/middleware.rs: auth.src/outbound/postgres.rs: the store of record for all broker state (registrations, refresh token bindings, pending authorizations, issued codes). Issued codes are stored by digest with their upstream tokens KMS-encrypted underMCP_OAUTH_KMS_KEY_ID.src/outbound/redis_cutover.rs: wraps the Postgres store during the move off Redis: Postgres first, Redis fallback with copy-forward, registrations and bindings mirrored to Redis, plus the startup backfill.src/outbound/email_sign_in.rs: emailed sign-in codes, through the authentication service's public login endpoints.src/outbound/fusionauth.rs,src/outbound/redis.rs: the upstream provider and the legacy Redis store (all adapters gated behind theoutboundfeature;inbound/outboundare each optional).
Scope
- Owns: DCR-compliant client registration, the sign-in chooser and email sign-in form, authorization-code issuance (including manual delivery for clients on another machine), refresh-token rotation/binding, and RFC 7009 revocation, all proxied in front of FusionAuth.
- Not here: the MCP tool surface itself →
services/agent_harness_service/src/public_mcp.rs.
Recipes
- Change redirect URI policy:
src/domain/redirect_uri.rs→ update the README section it implements →services/agent_harness_service/src/public_mcp.rs(DEFAULT_MCP_ALLOWED_REDIRECT_HOSTS) if the default allowlist changes. - Support a new HTTPS MCP client: nothing; users approve it on the consent
screen. Add its host to
DEFAULT_MCP_ALLOWED_REDIRECT_HOSTSonly to skip that screen for a client Macro has vetted. - Add a new grant type:
src/domain/models.rs→src/domain/service.rs→src/outbound/fusionauth.rs→src/inbound/axum_router.rs.
Checks
cargo test -p mcp_auth_proxy --all-features(SQLX_OFFLINEunset; the Postgres adapter tests need a migrated local MacroDB).
Shared listener
Use mounted_mcp_router in the harness so MCP does not override process
readiness at /health. The standalone mcp_router remains available to tests
and other library consumers. Both retain OAuth metadata, CORS, and bearer auth.
Gotchas
- Don't add an MCP client's host to FusionAuth's authorized origins
(
infra/stacks/fusionauth-instance/origins.ts)./authorizewithholds the client's Referer from FusionAuth, so a new client needs no origin entry. See README "Origin versus redirect URI". - Every
/authorizeresponse except the sign-in chooser sets the__Host-macro_mcp_oauthcookie and/oauth/callbackrequires it. Don't drop the check for trusted clients or relax the cookie toSameSite=None; see README "Consent and browser binding". The consent page's CSP has noform-action: browsers apply it to the form's redirect to FusionAuth. - The consent form re-posts the authorize request, so a new
AuthorizeRequestfield needs a hidden input intemplates/consent.html. The chooser repeats its query on its own. - The manual delivery page puts the callback URL in a shell command. Don't widen
RedirectUriPolicy::allows_manual_deliverypast characters that are inert in single quotes; see README "Signing in from another machine". - Pending flows are consumed only by a callback or a redeemed email code. Email
steps read them with
find_pending, so a mistyped code doesn't end the sign-in. client_idis not a secret; every endpoint must still check it against a live registration — see README "Which client a grant belongs to" before changing token/refresh validation.- Refresh tokens are bound by SHA-256 digest with rotate-before-drop ordering; don't weaken that to avoid a race, and remember pre-binding-era refresh tokens have no binding (clients reauthorize once).
- A binding carries the grant id of its token family; rotation must copy it
and refresh must check the revoked-grant marker, or
/revokestops covering rotated tokens. Bindings stored as a bare client id are their own family. - Upstream grants fail with
UpstreamGrantError(domain/ports.rs). Keep a grant FusionAuth refused asInvalidGrantso/tokenanswers400 invalid_grant; a 5xx tells clients to retry a token that can never work. See README "Token endpoint errors". - Redis is legacy. Write new state to Postgres only; the cutover module's
Redis mirroring exists solely for replicas on the previous build. Remove it
only after a deploy that started once no replica ran the Redis-only build
has logged
backfilled MCP OAuth state from legacy Redisin each environment (an earlier backfill can miss entries those replicas wrote late); then wirePostgresAuthStoredirectly and deleteredis.rsandredis_cutover.rs.
Related
Skill:
new-service(for how this is wired as a dependency, not a deploy)Only verified Macro JWT session provenance becomes
ManagedAgentSession; external MCP callers remain uncorrelated.