mix ash_ai.gen.mcp_oauth (ash_ai v1.5.6)

Copy Markdown View Source

Generates encrypted storage and routes for connecting to MCP servers that use OAuth

AshAi.Mcp.OAuth keeps tokens, client registrations, and authorizations in progress in an AshAi.Mcp.OAuth.Store that your application provides. This generates one backed by ash_postgres, with the secrets encrypted by ash_cloak, and the routes that send a user to authorize an MCP server and bring them back. See the "MCP Client Authorization" guide to write a store of your own instead.

Example

mix ash_ai.gen.mcp_oauth --user MyApp.Accounts.User

Options

  • --user - The user resource whose tokens are stored. Defaults to YourApp.Accounts.User when it exists. Tokens then belong to a user and are deleted with them, and the routes are generated, reading the user from conn.assigns.current_user. Without a user resource, tokens are stored under an opaque owner and the routes are left to you.
  • --domain - The domain for the generated resources. Defaults to YourApp.McpAuth.
  • --vault - The Cloak.Vault that encrypts the secrets. Defaults to YourApp.Vault, which is generated if it doesn't exist.
  • --route - Where the routes are mounted. Defaults to /mcp-auth.
  • --yes - Skip confirmation prompts.

What gets generated

  • The ash_cloak and cloak dependencies.
  • A vault, unless one exists, started by your application. Its key is configured in config/dev.exs and config/test.exs, and read from the CLOAK_KEY environment variable in production.
  • Resources whose data is encrypted:
    • Token - the tokens a user holds for an MCP server, deleted with the user.
    • Client - clients registered for each MCP server through Dynamic Client Registration.
    • PendingAuthorization - authorizations in progress, keyed by a digest of their state. Abandoned ones are deleted after an hour.
  • YourApp.McpAuth.Store, the AshAi.Mcp.OAuth.Store. Token refreshes take a lease on the token row, so they're serialized across nodes without holding a database connection.
  • YourApp.McpAuth.options/1, the AshAi.Mcp.OAuth options for a user, YourApp.McpAuth.allowed_private_hosts/0, which allows localhost in development, and YourApp.McpAuth.disconnect_all/1, which revokes a user's tokens. Call it before deleting a user, since deleting the user deletes their tokens without revoking them.
  • With a user resource and a Phoenix router, YourAppWeb.McpAuthController and its routes:
    • POST /mcp-auth/authorize sends the user to authorize an MCP server.
    • GET /mcp-auth/callback stores the token and sends the user back.
    • DELETE /mcp-auth/connection disconnects the user from an MCP server, revoking their tokens there.
    • GET /mcp-auth/client-metadata.json serves the Client ID Metadata Document, which authorization servers are offered when your endpoint's URL is HTTPS.