Protect MCP servers and APIs

import os

from fastmcp import FastMCP
from keycardai.fastmcp import AuthProvider

auth_provider = AuthProvider(
    zone_url=os.getenv("KEYCARD_ISSUER", "<keycard-issuer-url>"),
    mcp_server_name="Hello World Server",
    mcp_server_url=os.getenv("MCP_SERVER_URL", "http://localhost:8000"),
)

auth = auth_provider.get_remote_auth_provider()
mcp = FastMCP("Hello World Server", auth=auth)


@mcp.tool()
def hello_world(name: str) -> str:
    """Say hello to an authenticated user."""
    return f"Hello, {name}! You are authenticated."


def main():
    mcp.run(transport="streamable-http")


if __name__ == "__main__":
    main()

import express from "express";
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { mcpAuthMetadataRouter } from "@keycardai/mcp/server/auth/router";
import { requireBearerAuth } from "@keycardai/mcp/server/auth/middleware/bearerAuth";

const ZONE_URL = process.env.KEYCARD_ISSUER ?? "<keycard-issuer-url>"; // from Settings → Connection
const PORT = Number(process.env.PORT ?? 8080);

const app = express();
app.use(express.json());

// OAuth metadata endpoints (unauthenticated)
app.use(
  mcpAuthMetadataRouter({
    oauthMetadata: { issuer: ZONE_URL },
    resourceName: "Hello World MCP Server",
  }),
);

// MCP transport (protected by bearer auth)
app.post(
  "/mcp",
  requireBearerAuth({
    issuers: ZONE_URL,
    // Bind accepted tokens to this server's Resource identifier.
    audiences: `http://localhost:${PORT}/mcp`,
  }),
  async (req, res) => {
    const server = new McpServer({ name: "Hello World Server", version: "1.0.0" });

    server.tool(
      "hello_world",
      "Say hello to an authenticated user.",
      { name: z.string().describe("Name to greet") },
      async ({ name }) => ({
        content: [{ type: "text", text: `Hello, ${name}! You are authenticated.` }],
      }),
    );

    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  },
);

// Stateless server: no SSE stream and no session to end
app.get("/mcp", (_req, res) => { res.set("Allow", "POST").status(405).end(); });
app.delete("/mcp", (_req, res) => { res.set("Allow", "POST").status(405).end(); });

app.listen(PORT, () => {
  console.log(`Hello World MCP Server running on http://localhost:${PORT}`);
});

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")
  serverURL := os.Getenv("MCP_SERVER_URL")
  if serverURL == "" {
    serverURL = "http://localhost:8080"
  }

  // Build the MCP server with your preferred library (mcp-go here)
  s := server.NewMCPServer("Hello World Server", "1.0.0")
  s.AddTool(
    mcpgo.NewTool("hello_world",
      mcpgo.WithDescription("Say hello to an authenticated user."),
      mcpgo.WithString("name", mcpgo.Required()),
    ),
    func(ctx context.Context, req mcpgo.CallToolRequest) (*mcpgo.CallToolResult, error) {
      name, _ := req.GetArguments()["name"].(string)
      return mcpgo.NewToolResultText(
        fmt.Sprintf("Hello, %s! You are authenticated.", name),
      ), nil
    },
  )

  // The verifier trusts only tokens issued by your Zone, bound to this Resource
  verifier, err := mcp.NewZoneTokenVerifier(issuer, oauth.WithAudiences(serverURL+"/mcp"))
  if err != nil {
    log.Fatal(err)
  }

  mux := http.NewServeMux()

  // OAuth metadata endpoints (unauthenticated)
  mux.Handle("/.well-known/", mcp.AuthMetadataHandler(
    mcp.WithIssuer(issuer),
    mcp.WithResourceName("Hello World MCP Server"),
  ))

  // MCP transport (protected by bearer auth)
  mux.Handle("/mcp", mcp.RequireBearerAuth(verifier)(
    server.NewStreamableHTTPServer(s),
  ))

  log.Printf("Hello World MCP Server running on %s", serverURL)
  log.Fatal(http.ListenAndServe(":8080", mux))
}

import os
from fastapi import FastAPI, Request
from keycardai.starlette import AuthProvider, requires

ZONE_URL = os.environ["KEYCARD_ISSUER"]
# The Resource identifier you registered in Keycard. Binding it here means a
# token minted for any other resource is rejected.
API_URL = "http://localhost:8080"

auth = AuthProvider(zone_url=ZONE_URL, audience=API_URL)

app = FastAPI()
auth.install(app)  # mounts /.well-known/* and auth middleware


@app.get("/health")
async def health():
    return {"ok": True}


@app.get("/api/data")
@requires("authenticated")
async def get_data(request: Request):
    user = request.user
    # Identify the caller by keycard_app_id, not client_id (the credential).
    # sub_profile is "user" when the token's subject is a user, "app" otherwise.
    return {
        "data": "hello from protected API",
        "meta": {
            "application": user.keycard_app_id,
            "subject": user.sub,
            "subject_type": user.sub_profile,
            "scopes": user.scopes,
        },
    }

import express from "express";
import {
  requireBearerAuth,
  keycardMetadataRouter,
  type AuthenticatedRequest,
} from "@keycardai/express";

const ZONE_URL = process.env.KEYCARD_ISSUER!;
const PORT = process.env.PORT ?? "8080";
// The Resource identifier you registered in Keycard.
const API_URL = "http://localhost:8080";
const app = express();

// Discovery endpoints (unauthenticated).
app.use(
  keycardMetadataRouter({
    issuer: ZONE_URL,
    resourceName: "My API",
    scopesSupported: ["read", "write", "admin"],
  }),
);

// Bearer auth middleware. Applied per-route, not globally, so discovery
// endpoints remain accessible. `zoneUrl` pins the verifier to your zone
// so forged tokens from any other issuer are rejected before any JWKS lookup;
// `audience` binds accepted tokens to this API, so a token minted for another
// resource is rejected too.
const auth = requireBearerAuth({
  zoneUrl: ZONE_URL,
  audience: API_URL,
  requiredScopes: ["read"],
});

app.get("/api/data", auth, (req, res) => {
  // Identify the caller by keycardAppId, not clientId (the credential).
  // subProfile is "user" when the token's subject is a user, "app" otherwise.
  const { keycardAppId, sub, subProfile, scopes } = (req as AuthenticatedRequest).auth;
  res.json({
    data: "hello from protected API",
    meta: { application: keycardAppId, subject: sub, subject_type: subProfile, scopes },
  });
});

app.listen(Number(PORT), () => console.log(`Protected API listening on :${PORT}`));

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "os"

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

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

    mux := http.NewServeMux()

    // Discovery endpoints (unauthenticated).
    mux.Handle("/.well-known/", mcp.AuthMetadataHandler(
        mcp.WithIssuer(zoneURL),
        mcp.WithResourceName("My API"),
        mcp.WithScopesSupported([]string{"read", "write", "admin"}),
    ))

    // The verifier is pinned to your zone so forged tokens from any other
    // issuer are rejected before any JWKS lookup, and bound to this API's
    // Resource identifier so a token minted for another resource is rejected too.
    verifier, err := mcp.NewZoneTokenVerifier(zoneURL, oauth.WithAudiences("http://localhost:8080"))
    if err != nil {
        log.Fatal(err)
    }

    // Bearer auth middleware. Applied per route, not globally, so discovery
    // endpoints remain accessible.
    auth := mcp.RequireBearerAuth(verifier, mcp.WithRequiredScopes("read"))

    mux.Handle("GET /api/data", auth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        authInfo := mcp.AuthInfoFromRequest(r)
        w.Header().Set("Content-Type", "application/json")
        // Identify the caller by KeycardAppID, not ClientID (the credential).
        // SubProfile is "user" when the token's subject is a user, "app" otherwise.
        json.NewEncoder(w).Encode(map[string]any{
            "data": "hello from protected API",
            "meta": map[string]any{
                "application":  authInfo.KeycardAppID,
                "subject":      authInfo.Subject,
                "subject_type": authInfo.SubProfile,
                "scopes":       authInfo.Scopes,
            },
        })
    })))

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(map[string]bool{"ok": true})
    })

    log.Println("Protected API listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

import asyncio, os, httpx
from keycardai.oauth.pkce import authenticate

async def get_subject_token():
    async with httpx.AsyncClient() as http:
        r = await http.get("http://localhost:8080/api/data")
        www_auth = r.headers["www-authenticate"]

    token = await authenticate(
        client_id=os.environ["KEYCARD_CLIENT_ID"],
        client_secret=os.environ["KEYCARD_CLIENT_SECRET"],
        resource_url="http://localhost:8080",
        www_authenticate_header=www_auth,
        scopes=["read"],
    )
    return token.access_token

import { authenticate } from "@keycardai/oauth";

async function getSubjectToken() {
  const token = await authenticate(process.env.KEYCARD_ISSUER!, {
    clientId: process.env.KEYCARD_CLIENT_ID!,
    clientSecret: process.env.KEYCARD_CLIENT_SECRET!,
    resource: "http://localhost:8080",
    port: 8765,
    scopes: ["read"],
  });
  return token.accessToken;
}

package main

import (
    "context"
    "os"

    "github.com/keycardai/go-sdk/oauth"
)

func getSubjectToken(ctx context.Context) (string, error) {
    token, err := oauth.Authenticate(ctx, os.Getenv("KEYCARD_ISSUER"), oauth.AuthenticateRequest{
        ClientID:     os.Getenv("KEYCARD_CLIENT_ID"),
        ClientSecret: os.Getenv("KEYCARD_CLIENT_SECRET"),
        Resource:     "http://localhost:8080",
        CallbackPort: 8765,
        Scopes:       []string{"read"},
    })
    if err != nil {
        return "", err
    }
    return token.AccessToken, nil
}

require "keycardai/oauth"

def get_subject_token
  token = Keycardai::OAuth.authenticate(
    issuer: ENV.fetch("KEYCARD_ISSUER"),
    client_id: ENV.fetch("KEYCARD_CLIENT_ID"),
    client_secret: ENV.fetch("KEYCARD_CLIENT_SECRET"),
    resources: ["http://localhost:8080"],
    port: 8765,
    scope: "read",
  )
  token.access_token
end

import os

import httpx
from keycardai.oauth import AsyncClient, BasicAuth
from keycardai.oauth.types.models import TokenExchangeRequest


async def main():
    zone_url = os.environ["KEYCARD_ISSUER"]
    client_id = os.environ["KEYCARD_CLIENT_ID"]
    client_secret = os.environ["KEYCARD_CLIENT_SECRET"]
    user_access_token = await get_subject_token()  # the PKCE helper above

    async with AsyncClient(zone_url, auth=BasicAuth(client_id, client_secret)) as client:
        response = await client.exchange_token(TokenExchangeRequest(
            subject_token=user_access_token,
            resource="http://localhost:8080",
            scope="read",
        ))

        async with httpx.AsyncClient() as http:
            data = await http.get(
                "http://localhost:8080/api/data",
                headers={"Authorization": f"Bearer {response.access_token}"},
            )
    print(data.json())


asyncio.run(main())

import { TokenExchangeClient } from "@keycardai/oauth/tokenExchange";

async function main() {
  const exchange = new TokenExchangeClient(process.env.KEYCARD_ISSUER!, {
    clientId: process.env.KEYCARD_CLIENT_ID!,
    clientSecret: process.env.KEYCARD_CLIENT_SECRET!,
  });

  const userAccessToken = await getSubjectToken(); // the PKCE helper above

  const result = await exchange.exchangeToken({
    subjectToken: userAccessToken,
    resource: "http://localhost:8080",
    scope: "read",
  });

  const data = await fetch("http://localhost:8080/api/data", {
    headers: { Authorization: `Bearer ${result.accessToken}` },
  });
  console.log(await data.json());
}

main();

package main

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

    "github.com/keycardai/go-sdk/oauth"
)

func main() {
    ctx := context.Background()

    userAccessToken, err := getSubjectToken(ctx) // the PKCE helper above
    if err != nil {
        log.Fatal(err)
    }

    exchange := oauth.NewTokenExchangeClient(
        os.Getenv("KEYCARD_ISSUER"),
        oauth.WithClientCredentials(os.Getenv("KEYCARD_CLIENT_ID"), os.Getenv("KEYCARD_CLIENT_SECRET")),
    )

    result, err := exchange.ExchangeToken(ctx, oauth.TokenExchangeRequest{
        SubjectToken: userAccessToken,
        Resource:     "http://localhost:8080",
        Scope:        "read",
    })
    if err != nil {
        log.Fatal(err)
    }

    req, _ := http.NewRequestWithContext(ctx, "GET", "http://localhost:8080/api/data", nil)
    req.Header.Set("Authorization", "Bearer "+result.AccessToken)
    data, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer data.Body.Close()
    body, _ := io.ReadAll(data.Body)
    fmt.Println(string(body))
}

require "keycardai/oauth"
require "net/http"

exchange = Keycardai::OAuth::TokenExchangeClient.new(
  issuer: ENV.fetch("KEYCARD_ISSUER"),
  client_id: ENV.fetch("KEYCARD_CLIENT_ID"),
  client_secret: ENV.fetch("KEYCARD_CLIENT_SECRET"),
)

user_access_token = get_subject_token # the PKCE helper above

result = exchange.exchange_token(
  subject_token: user_access_token,
  resource: "http://localhost:8080",
  scope: "read",
)

data = Net::HTTP.get(
  URI("http://localhost:8080/api/data"),
  { "Authorization" => "Bearer #{result.access_token}" },
)
puts data