Connect to OAuth-protected MCP servers

Connect the MCP client

Point MCPClient at the hosted server’s URL and give it an OAuth provider:

1
import { Agent } from "@mastra/core/agent";
2
import { MCPClient, MCPOAuthClientProvider } from "@mastra/mcp";
3
import { serve } from "@astropods/adapter-mastra";
4
5
const provider = new MCPOAuthClientProvider({
6
  redirectUrl, // resolved in step 2
7
  clientMetadata: {
8
    client_name: "My Agent",
9
    redirect_uris: [redirectUrl],
10
    grant_types: ["authorization_code", "refresh_token"],
11
    response_types: ["code"],
12
    token_endpoint_auth_method: "none", // public client + PKCE
13
  },
14
  storage: tokenStore, // step 3
15
});
16
17
const mcp = new MCPClient({
18
  servers: {
19
    myServer: { url: new URL("https://mcp.example.com/mcp"), authProvider: provider },
20
  },
21
});
22
23
const agent = new Agent({
24
  name: "My Agent",
25
  model: "anthropic/claude-sonnet-4-5",
26
  instructions: "Answer questions using the connected tools.",
27
  tools: await mcp.listTools(), // namespaced as <server>_<tool>
28
});
29
30
serve(agent);

listTools() skips servers that aren’t authorized yet (it logs and moves on), so your agent still boots before any OAuth has happened.

Build the redirect from your agent's public URL

The redirect URI must be a URL the browser can reach that lands back on your agent. Resolve it in priority order, explicit override, then the platform-injected public URL, then localhost for dev:

1
const CALLBACK_PATH = "/oauth/callback";
2
3
const redirectUrl =
4
  process.env.OAUTH_REDIRECT_URL ??
5
  (process.env.ASTRO_EXTERNAL_AGENT_URL
6
    ? `${process.env.ASTRO_EXTERNAL_AGENT_URL.replace(/\/+$/, "")}${CALLBACK_PATH}`
7
    : `http://localhost:${process.env.PORT ?? 8808}${CALLBACK_PATH}`);

ASTRO_EXTERNAL_AGENT_URL is injected only when your agent exposes a public endpoint. To get one, and to actually receive the redirect, declare a frontend interface and serve the callback path:

1
agent:
2
  build:
3
    context: .
4
    dockerfile: Dockerfile
5
  interfaces:
6
    frontend: true    # public host + ASTRO_EXTERNAL_AGENT_URL, routes :443 -> :80
7
    messaging: true   # keep the chat interface

Declaring frontend: true provisions a public HTTPS host, injects ASTRO_EXTERNAL_AGENT_URL, sets PORT=80, and routes the public host to your container on port 80. See Serve a frontend from your agent for the full topology.

Serve the callback on PORT (80 in production) — the same process that runs serve(agent) can host a tiny HTTP listener:

1
Bun.serve({
2
  port: Number(process.env.PORT ?? 8808),
3
  fetch: async (req) => {
4
    const url = new URL(req.url);
5
    if (url.pathname !== CALLBACK_PATH) {
6
      return new Response("ok", { status: 200 }); // 200 so ingress health checks pass
7
    }
8
    const code = url.searchParams.get("code");
9
    // hand `code` to your provider/transport to finish the exchange, then 200
10
    return new Response("Connected — you can close this tab.");
11
  },
12
});

1
# ... build ...
2
EXPOSE 80
3
CMD ["bun", "run", "agent/index.ts"]

With this in place, the OAuth redirect lands on https://<your-host>/oauth/callback, the ingress routes it to your container, and the flow completes without a manual step.

Persist tokens in a writable store

The production container filesystem is read-only, so a file-based token store is wiped on every restart. Persist OAuth tokens (and the dynamic client registration) in a writable store — a redis knowledge store entry is the simplest:

1
knowledge:
2
  cache:
3
    provider: redis   # injects REDIS_URL

Implement @mastra/mcp’s OAuthStorage interface (get / set / delete) against Redis when REDIS_URL is present, and fall back to a local file in dev. Tokens then survive restarts, and the MCP SDK refreshes expired access tokens from the stored refresh token automatically.

Drive consent from the conversation

Because a deployed agent is headless, let it hand the user the authorization URL in chat. Expose a Mastra tool that starts the flow and returns the URL:

1
import { createTool } from "@mastra/core/tools";
2
import { z } from "zod";
3
4
const connectService = createTool({
5
  id: "connect_service",
6
  description: "Begin connecting a tool provider via OAuth; returns a URL to open.",
7
  inputSchema: z.object({ service: z.string() }),
8
  execute: async ({ service }) => {
9
    const authorizationUrl = await startAuthorization(service); // triggers provider redirect
10
    return { authorizationUrl };
11
  },
12
});

The user opens the URL and approves; with the frontend callback from step 2 the connection completes on its own, and the agent re-lists that server’s tools so they’re immediately usable.

Deploy and verify

Deploy the blueprint and open the URL it returns:

$
ast blueprint deploy <name>

Start the connect flow from chat, open the authorization URL, and approve. The callback lands on https://<your-host>/oauth/callback, and you should see Connected.