MCP

OAuth authentication for MCP servers. Bearer middleware, metadata endpoints, and grant decorators.

The MCP package adds OAuth-based authentication to your MCP server. It handles bearer token verification, serves OAuth metadata endpoints, and provides grant decorators for delegated access to external APIs.

When to Use

Building an MCP server that requires user authentication
Adding delegated access to external APIs (GitHub, Google, etc.) from MCP tools
Serving OAuth .well-known metadata for MCP clients

Installation

# Standard MCP SDK
pip install keycardai-mcp

# FastMCP framework (see FastMCP section below)
pip install keycardai-fastmcp

npm install @keycardai/mcp

go get github.com/keycardai/go-sdk

bundle add keycardai-mcp

Key Exports

keycardai.mcp.server.auth

Export	Description
`AuthProvider`	Core auth provider. Wraps your MCP app with OAuth middleware
`AccessContext`	Token exchange result. Check errors, access tokens per resource
`TokenVerifier`	Verify incoming bearer tokens
`ClientSecret`	Application credential using client ID + secret
`WebIdentity`	Application credential using private key JWT
`EKSWorkloadIdentity`	Application credential for EKS environments

@keycardai/mcp

Export	Description
`AuthProvider`	Core auth provider with `grant()` middleware
`AccessContext`	Token exchange result. Check errors, access tokens per resource
`mcpAuthMetadataRouter`	Express router for OAuth `.well-known` endpoints
`requireBearerAuth`	Express middleware for bearer token verification
`ClientSecret`	Application credential using client ID + secret
`WebIdentity`	Application credential using private key JWT
`EKSWorkloadIdentity`	Application credential for EKS environments

go-sdk/mcp. Composable HTTP middleware for MCP server auth

Export	Description
`AuthProvider`	Core auth provider with `Grant()` middleware
`AccessContext`	Token exchange result. Check errors, access tokens per resource
`WithUserIdentifier`	Grant option: impersonate a resolved user instead of exchanging the caller’s token
`AuthMetadataHandler`	`http.Handler` for OAuth `.well-known` endpoints
`RequireBearerAuth`	`http.Handler` middleware for bearer token verification
`AuthInfoFromContext`	Retrieve auth info from `context.Context` (for tool handlers)
`AccessContextFromContext`	Retrieve access context from `context.Context` (for tool handlers)
`ClientSecretCredential`	Application credential using client ID + secret (`NewClientSecret`)
`WebIdentityCredential`	Application credential using private key JWT (`NewWebIdentity`)
`EKSWorkloadIdentity`	Application credential for EKS environments

keycardai-mcp. Composable Rack middleware for MCP server auth

Export	Description
`AuthProvider`	Core auth provider with `grant` middleware
`AccessContext`	Token exchange result. Check errors, access tokens per resource
`MetadataApp`	Rack app for OAuth `.well-known` endpoints
`RequireBearerAuth`	Rack middleware for bearer token verification
`Keycardai::MCP.auth_info`	Read the verified token from the Rack env (for handlers)
`Keycardai::MCP.access_context`	Read the `AccessContext` from the Rack env (for handlers)

Quickstart

Hello World: Authenticated MCP Server

from mcp.server.mcpserver import MCPServer
from keycardai.mcp.server.auth import AuthProvider

mcp = MCPServer("Hello World Server")
auth_provider = AuthProvider(
    zone_id="<zone-id>",
    mcp_server_name="Hello World Server",
    mcp_server_url="http://localhost:8000/",
    audience="http://localhost:8000/mcp",
)

@mcp.tool()
async def hello() -> str:
    return "Hello from a protected MCP server!"

# Wrap the MCP app with authentication
app = auth_provider.app(mcp)

import express from "express";
import { mcpAuthMetadataRouter } from "@keycardai/mcp/server/auth/router";
import { requireBearerAuth } from "@keycardai/mcp/server/auth/middleware/bearerAuth";

const ISSUER = process.env.KEYCARD_ISSUER!;
const app = express();

// Serve OAuth metadata
app.use(
  mcpAuthMetadataRouter({
    oauthMetadata: { issuer: ISSUER },
    scopesSupported: ["mcp:tools"],
    resourceName: "Hello World MCP Server",
  }),
);

// Protect routes with bearer token verification. `issuers` is required.
// It pins the verifier to your zone so forged tokens from any other
// issuer are rejected before any JWKS lookup.
app.use(
  "/api",
  requireBearerAuth({
    issuers: ISSUER,
    // Bind accepted tokens to this server's Resource identifier.
    audiences: "http://localhost:8000/api",
    requiredScopes: ["mcp:tools"],
  }),
);

app.get("/api/whoami", (req, res) => {
  res.json({ message: "Hello from a protected MCP server!" });
});

app.listen(8000);

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/keycardai/go-sdk/mcp"
    "github.com/keycardai/go-sdk/oauth"
    mcpgo "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    issuer := os.Getenv("KEYCARD_ISSUER")

    // Create MCP server with your preferred library
    s := server.NewMCPServer("Hello World Server", "1.0.0")
    s.AddTool(
        mcpgo.NewTool("hello",
            mcpgo.WithDescription("Say hello."),
            mcpgo.WithString("name", mcpgo.Required()),
        ),
        func(ctx context.Context, req mcpgo.CallToolRequest) (*mcpgo.CallToolResult, error) {
            name, _ := req.GetArguments()["name"].(string)
            authInfo := mcp.AuthInfoFromContext(ctx)
            return mcpgo.NewToolResultText(
                fmt.Sprintf("Hello, %s! Client: %s", name, authInfo.ClientID),
            ), nil
        },
    )

    // Mount Keycard auth on your own mux
    httpMux := http.NewServeMux()
    httpMux.Handle("/.well-known/", mcp.AuthMetadataHandler(
        mcp.WithIssuer(issuer),
        mcp.WithScopesSupported([]string{"mcp:tools"}),
        mcp.WithResourceName("Hello World Server"),
    ))
    verifier, _ := mcp.NewZoneTokenVerifier(issuer, oauth.WithAudiences("http://localhost:8080/mcp"))
    httpMux.Handle("/mcp", mcp.RequireBearerAuth(
        verifier,
        mcp.WithRequiredScopes("mcp:tools"),
    )(server.NewStreamableHTTPServer(s)))

    log.Fatal(http.ListenAndServe(":8080", httpMux))
}

# config.ru. Run with: bundle exec rackup -p 8000
require "keycardai/mcp"
require "mcp"

issuer = ENV.fetch("KEYCARD_ISSUER")

# Create the MCP server with the official mcp gem
mcp_server = MCP::Server.new(name: "Hello World Server", version: "1.0.0")
mcp_server.define_tool(
  name: "hello",
  description: "Say hello.",
  input_schema: { properties: { name: { type: "string" } }, required: [] },
) do |name: "world", server_context: nil|
  MCP::Tool::Response.new([{ type: "text", text: "Hello, #{name}!" }])
end

# Serve OAuth metadata and require a bearer token on /mcp, bound to this
# server's Resource identifier
verifier = Keycardai::OAuth::TokenVerifier.new(issuers: issuer, audiences: "http://localhost:8000/mcp")
metadata = Keycardai::MCP::MetadataApp.new(
  issuer: issuer,
  resource_name: "Hello World Server",
  scopes_supported: ["mcp:tools"],
)

mcp_endpoint = lambda do |env|
  body = env["rack.input"].read
  [200, { "content-type" => "application/json" }, [mcp_server.handle_json(body)]]
end
protected_mcp = Keycardai::MCP::RequireBearerAuth.new(
  mcp_endpoint, verifier: verifier, required_scopes: ["mcp:tools"],
)

run lambda { |env|
  case env["PATH_INFO"]
  when %r{\A/\.well-known/} then metadata.call(env)
  when "/mcp" then protected_mcp.call(env)
  else [404, { "content-type" => "application/json" }, ['{"error":"not_found"}']]
  end
}

Delegated Access: Call External APIs

import httpx
from mcp.server.mcpserver import Context, MCPServer
from keycardai.mcp.server.auth import AccessContext, AuthProvider, ClientSecret

auth_provider = AuthProvider(
    zone_id="<zone-id>",
    mcp_server_name="GitHub Server",
    mcp_server_url="http://localhost:8000/",
    audience="http://localhost:8000/mcp",
    application_credential=ClientSecret(("client_id", "client_secret")),
)

mcp = MCPServer("GitHub Server")

@mcp.tool()
@auth_provider.grant("https://api.github.com")
async def get_repos(access_ctx: AccessContext, ctx: Context) -> dict:
    if access_ctx.has_errors():
        return {"error": access_ctx.get_errors()}

    token = access_ctx.access("https://api.github.com").access_token
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.github.com/user/repos",
            headers={"Authorization": f"Bearer {token}"},
        )
        return resp.json()

app = auth_provider.app(mcp)

@grant injects the AccessContext parameter and strips it from the tool schema, so the model never sees it. The decorated function needs both an AccessContext-annotated and a Context-annotated parameter.

import express from "express";
import { AuthProvider } from "@keycardai/mcp/server/auth/provider";
import { ClientSecret } from "@keycardai/mcp/server/auth/credentials";
import type { DelegatedRequest } from "@keycardai/mcp/server/auth/provider";

const authProvider = new AuthProvider({
  zoneUrl: process.env.KEYCARD_ISSUER!,
  applicationCredential: new ClientSecret(
    process.env.KEYCARD_CLIENT_ID!,
    process.env.KEYCARD_CLIENT_SECRET!,
  ),
});

const app = express();

app.get(
  "/api/repos",
  authProvider.grant("https://api.github.com"),
  async (req, res) => {
    const { accessContext } = req as DelegatedRequest;

    if (accessContext.hasErrors()) {
      res.status(502).json({ error: accessContext.getErrors() });
      return;
    }

    const token = accessContext.access("https://api.github.com").accessToken;
    const resp = await fetch("https://api.github.com/user/repos", {
      headers: { Authorization: `Bearer ${token}` },
    });
    res.json(await resp.json());
  },
);

app.listen(8000);

package main

import (
    "context"
    "io"
    "log"
    "net/http"
    "os"

    "github.com/keycardai/go-sdk/mcp"
    "github.com/keycardai/go-sdk/oauth"
    mcpgo "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    s := server.NewMCPServer("GitHub Server", "1.0.0")
    s.AddTool(
        mcpgo.NewTool("get_repos", mcpgo.WithDescription("List user repos")),
        func(ctx context.Context, req mcpgo.CallToolRequest) (*mcpgo.CallToolResult, error) {
            ac := mcp.AccessContextFromContext(ctx)
            if ac.HasErrors() {
                return mcpgo.NewToolResultError("Token exchange failed"), nil
            }

            token, _ := ac.Access("https://api.github.com")
            ghReq, _ := http.NewRequestWithContext(ctx, "GET",
                "https://api.github.com/user/repos", nil)
            ghReq.Header.Set("Authorization", "Bearer "+token.AccessToken)

            resp, _ := http.DefaultClient.Do(ghReq)
            defer resp.Body.Close()
            body, _ := io.ReadAll(resp.Body)
            return mcpgo.NewToolResultText(string(body)), nil
        },
    )

    // Set up auth provider for token exchange
    credential, _ := mcp.NewClientSecret(
        os.Getenv("KEYCARD_CLIENT_ID"),
        os.Getenv("KEYCARD_CLIENT_SECRET"),
    )
    authProvider, _ := mcp.NewAuthProvider(
        mcp.WithZoneURL(os.Getenv("KEYCARD_ISSUER")),
        mcp.WithApplicationCredential(credential),
    )

    httpMux := http.NewServeMux()
    httpMux.Handle("/.well-known/", mcp.AuthMetadataHandler(
        mcp.WithIssuer(os.Getenv("KEYCARD_ISSUER")),
        mcp.WithScopesSupported([]string{"mcp:tools"}),
        mcp.WithResourceName("GitHub Server"),
    ))
    verifier, _ := mcp.NewZoneTokenVerifier(os.Getenv("KEYCARD_ISSUER"), oauth.WithAudiences("http://localhost:8080/mcp"))
    httpMux.Handle("/mcp", mcp.RequireBearerAuth(
        verifier,
        mcp.WithRequiredScopes("mcp:tools"),
    )(authProvider.Grant([]string{"https://api.github.com"})(
        server.NewStreamableHTTPServer(s),
    )))

    log.Fatal(http.ListenAndServe(":8080", httpMux))
}

require "net/http"
require "keycardai/mcp"

issuer = ENV.fetch("KEYCARD_ISSUER")

# Set up the auth provider for token exchange
provider = Keycardai::MCP::AuthProvider.new(
  zone_url: issuer,
  client_id: ENV.fetch("KEYCARD_CLIENT_ID"),
  client_secret: ENV.fetch("KEYCARD_CLIENT_SECRET"),
)

metadata = Keycardai::MCP::MetadataApp.new(
  issuer: issuer,
  resource_name: "GitHub Server",
  scopes_supported: ["mcp:tools"],
)

get_repos = lambda do |env|
  context = Keycardai::MCP.access_context(env)
  if context.errors?
    return [502, { "content-type" => "application/json" }, ['{"error":"token_exchange_failed"}']]
  end

  token = context.access("https://api.github.com").access_token
  uri = URI("https://api.github.com/user/repos")
  request = Net::HTTP::Get.new(uri, "authorization" => "Bearer #{token}")
  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
  [200, { "content-type" => "application/json" }, [response.body]]
end

# Verify the bearer token, then exchange it once per granted resource
protected_repos = Keycardai::MCP::RequireBearerAuth.new(
  provider.grant("https://api.github.com").new(get_repos),
  verifier: provider.token_verifier,
  required_scopes: ["mcp:tools"],
)

run lambda { |env|
  case env["PATH_INFO"]
  when %r{\A/\.well-known/} then metadata.call(env)
  when "/api/repos" then protected_repos.call(env)
  else [404, { "content-type" => "application/json" }, ['{"error":"not_found"}']]
  end
}

grant returns a Rack middleware class: the Ruby equivalent of Python’s @grant decorator and TypeScript’s route middleware. A failing resource never aborts the request; the error lands on the AccessContext.

Impersonation: Act as a Specific User

By default, grant() exchanges the caller’s bearer token — the tool acts as whoever is calling. When the server must act as a named user instead — a scheduled job, a queue worker, or a tool that operates on another user’s data — supply a user-identifier resolver and the grant impersonates that user via a substitute-user token exchange. The server’s own application credential authenticates the exchange; no user token is needed. See Act on Behalf of Absent Users for the consent setup and policy requirements.

@mcp.tool()
@auth_provider.grant(
    "https://api.github.com",
    user_identifier=lambda **kwargs: kwargs["user_email"],
)
async def get_repos(access_ctx: AccessContext, ctx: Context, user_email: str) -> dict:
    if access_ctx.has_errors():
        return {"error": access_ctx.get_errors()}

    token = access_ctx.access("https://api.github.com").access_token
    # Call the API as user_email...

The user_identifier callable receives the tool’s keyword arguments and returns the identifier string.

app.get(
  "/api/repos",
  authProvider.grant("https://api.github.com", {
    userIdentifier: (req) => resolveUserIdentifier(req),
  }),
  async (req, res) => {
    const { accessContext } = req as DelegatedRequest;
    const token = accessContext.access("https://api.github.com").accessToken;
    // Call the API as the resolved user...
  },
);

The resolver runs once per request and may be async.

httpMux.Handle("/mcp", mcp.RequireBearerAuth(
    verifier,
    mcp.WithRequiredScopes("mcp:tools"),
)(authProvider.Grant([]string{"https://api.github.com"},
    mcp.WithUserIdentifier(func(r *http.Request) (string, error) {
        return mcp.AuthInfoFromRequest(r).Subject, nil
    }),
)(server.NewStreamableHTTPServer(s))))

If the resolver returns an error, the grant fails closed with a global error on the AccessContext.

protected_repos = Keycardai::MCP::RequireBearerAuth.new(
  provider.grant(
    "https://api.github.com",
    user_identifier: ->(env) { Keycardai::MCP.auth_info(env).subject },
  ).new(get_repos),
  verifier: provider.token_verifier,
  required_scopes: ["mcp:tools"],
)

user_identifier: accepts a string, or a callable that receives the Rack env and returns the identifier.

FastMCP Integration

The keycardai-fastmcp package provides a dedicated integration for Python’s FastMCP framework. It wraps the same auth primitives with FastMCP-specific APIs.

pip install keycardai-fastmcp

Upgrading a server from FastMCP 2.x? Migrate to FastMCP 3.0 covers the package rename and the await ctx.get_state() change, tool by tool.

Key Differences from `keycardai-mcp`

Feature	`keycardai-mcp`	`keycardai-fastmcp`
Framework	Standard MCP SDK (`mcp` 2.x)	FastMCP 3.x (`mcp` 1.x)
Auth setup	`auth_provider.app(mcp)`	`auth_provider.get_remote_auth_provider()`
Grant decorator	`@auth_provider.grant(resource)`	Same
Access context	Injected `AccessContext` parameter	`await ctx.get_state("keycardai")`
Testing	N/A	`mock_access_context` test utility

The two packages track different upstream majors on purpose: keycardai-mcp follows the standard MCP SDK 2.x line, while keycardai-fastmcp follows FastMCP 3.x, which still builds on mcp 1.x. Pick the one that matches your framework; neither replaces the other.

FastMCP Example

from fastmcp import Context, FastMCP
from keycardai.fastmcp import AuthProvider, ClientSecret, AccessContext

auth_provider = AuthProvider(
    zone_id="<zone-id>",
    mcp_server_name="GitHub API Server",
    mcp_server_url="http://localhost:8000/",
    application_credential=ClientSecret(("client_id", "client_secret")),
)

auth = auth_provider.get_remote_auth_provider()
mcp = FastMCP("GitHub API Server", auth=auth)

@mcp.tool()
@auth_provider.grant("https://api.github.com")
async def get_github_user(ctx: Context) -> dict:
    access_context: AccessContext = await ctx.get_state("keycardai")

    if access_context.has_errors():
        return {"error": access_context.get_errors()}

    token = access_context.access("https://api.github.com").access_token
    # Use token to call GitHub API...

Source

Python SDKkeycardai-mcp

TypeScript SDK@keycardai/mcp

Go SDKgo-sdk/mcp

Ruby SDKThe keycardai-mcp gem