Build an MCP Server

MCP servers expose tools to AI agents — but without authentication, any agent can call any tool with no accountability. Keycard adds OAuth-based authentication to your MCP server so that every tool call is tied to a verified user, scoped to explicit permissions, and logged for audit.

This guide walks through building a protected MCP server from scratch — first a hello world, then adding delegated access to external APIs — with examples in Python, TypeScript, and Go.

Tip

For complete, runnable code see the full examples: Python SDK | TypeScript SDK | Go SDK

Building with an AI agent? Point it at docs.keycard.ai/llms.txt for the full docs index, or docs.keycard.ai/guides/mcp-server.md for this guide with complete code examples.

Note

For SDK package details, installation, and API reference see the MCP package docs.

Prerequisites

• Python 3.10+, Node.js 18+, or Go 1.21+
• Keycard account with access to Console
• Cursor IDE or another MCP-compatible client for testing

Hello World MCP Server

Install Dependencies

Python

pip install keycardai-mcp-fastmcp fastmcp

TypeScript

npm install @keycardai/mcp @modelcontextprotocol/sdk express
npm install -D typescript @types/express

Go

go mod init my-mcp-server
go get github.com/keycardai/credentials-go/mcp

Register Your MCP Server in Keycard

Your MCP server needs to be registered as a protected Resource in Keycard so that AI agents can authenticate against it.

1. In Keycard Console, navigate to Resources → Create Resource

2. Configure the resource:

   Python

   Resource Name	My MCP Server (Local Dev)
   Resource Identifier	http://localhost:8000/mcp
   Credential Provider	Zone Provider

   TypeScript

   Resource Name	My MCP Server (Local Dev)
   Resource Identifier	http://localhost:8080/mcp
   Credential Provider	Zone Provider

   Go

   Resource Name	My MCP Server (Local Dev)
   Resource Identifier	http://localhost:8080/mcp
   Credential Provider	Zone Provider

3. Click Create

Note

The resource identifier must match your server’s MCP endpoint URL exactly.

Configure Environment

Create a .env file in your project root:

Python

KEYCARD_ZONE_ID=your-zone-id
MCP_SERVER_URL=http://localhost:8000

TypeScript

KEYCARD_ZONE_URL=https://your-zone-id.keycard.cloud
PORT=8080

Go

KEYCARD_ZONE_URL=https://your-zone-id.keycard.cloud
PORT=8080

Tip

Find your zone ID in Keycard Console → Zone Settings. The Python SDK uses the zone ID directly, while the TypeScript and Go SDKs use the full zone URL.

Write the Server

Python

import os

from fastmcp import FastMCP
from keycardai.mcp.integrations.fastmcp import AuthProvider

auth_provider = AuthProvider(
    zone_id=os.getenv("KEYCARD_ZONE_ID", "your-zone-id"),
    mcp_server_name="Hello World Server",
    mcp_base_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()

AuthProvider handles all OAuth metadata and token verification. It connects your server to your Keycard zone so that MCP clients can discover how to authenticate. get_remote_auth_provider() returns the auth configuration that FastMCP needs, and mcp.run() starts the server.

TypeScript

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

const ZONE_URL = process.env.KEYCARD_ZONE_URL ?? "https://your-zone.keycard.cloud";
const PORT = Number(process.env.PORT ?? 8080);

const app = express();

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

app.get("/api/whoami", (req, res) => {
  res.json({
    message: "Hello from Keycard!",
    authenticated: true,
  });
});

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

mcpAuthMetadataRouter serves the .well-known OAuth endpoints that MCP clients use to discover how to authenticate. Keycard handles token verification automatically — your server just needs to expose the metadata.

Go

package main

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

  "github.com/keycardai/credentials-go/mcp"
)

func main() {
  zoneURL := os.Getenv("KEYCARD_ZONE_URL")
  port := os.Getenv("PORT")
  if port == "" {
    port = "8080"
  }

  mux := http.NewServeMux()

  // Serve OAuth metadata endpoints
  mux.Handle("/.well-known/", mcp.AuthMetadataHandler(
    mcp.WithIssuer(zoneURL),
    mcp.WithScopesSupported([]string{"mcp:tools"}),
    mcp.WithResourceName("Hello World MCP Server"),
  ))

  mux.HandleFunc("GET /api/hello", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]any{
      "message":       "Hello from Keycard!",
      "authenticated": true,
    })
  })

  log.Printf("Hello World MCP Server running on http://localhost:%s", port)
  log.Fatal(http.ListenAndServe(":"+port, mux))
}

mcp.AuthMetadataHandler serves the .well-known OAuth endpoints that MCP clients use to discover how to authenticate. The Go SDK uses the standard net/http library — no frameworks required.

Run and Test

1. Start the server

   Python

   python -m my_server

   TypeScript

   npx tsx src/server.ts

   Go

   go run .

2. Configure your coding agent

   Add the MCP server to your agent’s configuration. Use the URL your server is running on (Python defaults to port 8000, TypeScript to 8080).

   Cursor — add to .cursor/mcp.json:

   {
     "mcpServers": {
       "my-mcp-server": {
         "url": "http://localhost:8000/mcp"
       }
     }
   }

   Claude Code — run in your terminal:

   claude mcp add --transport http my-mcp-server http://localhost:8000/mcp

3. Authenticate and test

   1. Restart your coding agent to detect the new MCP server
   2. Connect to the MCP server when prompted
   3. Complete the OAuth flow with Keycard
   4. Test the tool — ask your agent: "Run the hello_world tool with my name"

4. Verify in Keycard Console

   Check Audit Logs for:

   users:authenticate	You logged in successfully
   users:authorize	Your access was authorized
   credentials:issue	Access token was issued

Tip

See the full working examples: Python | TypeScript | Go

Add Delegated Access

Delegated access lets your MCP server call external APIs (like GitHub) on behalf of authenticated users using token exchange (RFC 8693). Keycard exchanges the user’s token for an API-specific token automatically.

Add GitHub from Resource Catalog

The Resource Catalog provides pre-configured integrations that auto-create the resource and provider for you.

1. In Keycard Console, navigate to Resources → Add Resource → Explore Resources
2. Select GitHub from the catalog
3. Enter your GitHub OAuth App credentials (Client ID and Client Secret)
4. The catalog will create the GitHub provider and resource automatically

Note

Don’t have a GitHub OAuth App yet? Create one at github.com/settings/developers. Set the callback URL to the OAuth Redirect URL from your Keycard zone settings.

Create Application Credentials

Your server needs application credentials to perform token exchange.

1. In Keycard Console, navigate to Applications → Create Application
2. Set the Provided Resource to your MCP server resource (e.g., My MCP Server (Local Dev))
3. Add the GitHub API resource as a Dependency
4. Generate Client Credentials (Client ID + Client Secret)
5. Save these credentials — you will need them in the next step

Update Environment

Add the application credentials to your .env:

Python

KEYCARD_ZONE_ID=your-zone-id
KEYCARD_CLIENT_ID=your-client-id
KEYCARD_CLIENT_SECRET=your-client-secret
MCP_SERVER_URL=http://localhost:8000

TypeScript

KEYCARD_ZONE_URL=https://your-zone-id.keycard.cloud
KEYCARD_CLIENT_ID=your-client-id
KEYCARD_CLIENT_SECRET=your-client-secret
PORT=8080

Go

KEYCARD_ZONE_URL=https://your-zone-id.keycard.cloud
KEYCARD_CLIENT_ID=your-client-id
KEYCARD_CLIENT_SECRET=your-client-secret
PORT=8080

Use the Grant Pattern

The key Keycard pattern for delegated access is the grant decorator/middleware. It tells Keycard to exchange the user’s token for an API-specific token before your tool runs:

Python

from keycardai.mcp.integrations.fastmcp import AccessContext, AuthProvider, ClientSecret

auth_provider = AuthProvider(
    zone_id=os.getenv("KEYCARD_ZONE_ID"),
    mcp_server_name="GitHub API Server",
    mcp_base_url=os.getenv("MCP_SERVER_URL", "http://localhost:8000"),
    application_credential=ClientSecret((
        os.getenv("KEYCARD_CLIENT_ID"),
        os.getenv("KEYCARD_CLIENT_SECRET"),
    )),
)

@mcp.tool()
@auth_provider.grant("https://api.github.com")
async def get_github_user(ctx: Context) -> dict:
    """Get the authenticated user's GitHub profile."""
    access_context: AccessContext = ctx.get_state("keycardai")

    if access_context.has_errors():
        return {"error": "Token exchange failed", "details": access_context.get_errors()}

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

The @auth_provider.grant("https://api.github.com") decorator tells Keycard to exchange the user’s token for a GitHub API token before the tool runs. The exchanged token is available via ctx.get_state("keycardai").

TypeScript

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: ZONE_URL,
  applicationCredential: new ClientSecret(CLIENT_ID, CLIENT_SECRET),
});

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

    if (accessContext.hasErrors()) {
      res.status(502).json({ error: "Token exchange failed" });
      return;
    }

    const token = accessContext.access("https://api.github.com").accessToken;
    // Use token to call GitHub API
  },
);

The authProvider.grant("https://api.github.com") middleware performs token exchange before your route handler runs. The exchanged token is available on req.accessContext.

Go

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

  "github.com/keycardai/credentials-go/mcp"
)

authProvider, err := mcp.NewAuthProvider(
  mcp.WithZoneURL(os.Getenv("KEYCARD_ZONE_URL")),
  mcp.WithApplicationCredential(mcp.NewClientSecret(
    os.Getenv("KEYCARD_CLIENT_ID"),
    os.Getenv("KEYCARD_CLIENT_SECRET"),
  )),
)

// Chain: bearer auth → grant → handler
handler := mcp.RequireBearerAuth(
  mcp.WithRequiredScopes("mcp:tools"),
)(authProvider.Grant("https://api.github.com")(
  http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ac := mcp.AccessContextFromRequest(r)

    if ac.HasErrors() {
      http.Error(w, "Token exchange failed", http.StatusBadGateway)
      return
    }

    token, _ := ac.Access("https://api.github.com")
    // Use token.AccessToken to call GitHub API
  }),
))

The authProvider.Grant("https://api.github.com") middleware performs token exchange before your handler runs. The exchanged token is available via mcp.AccessContextFromRequest(r).

Run and Test

1. Start the server

   Python

   python -m my_server

   TypeScript

   npx tsx src/server.ts

   Go

   go run .

2. Test in Cursor

   Ask Cursor: "Get my GitHub profile" — you should see your GitHub user data returned.

3. Verify in Keycard Console

   Check Audit Logs for token exchange events alongside the authentication events.

Tip

See the full working examples with complete API wrappers and multiple tools: Python | TypeScript | Go

Deploy to Production

When deploying your MCP server to production:

• Update the resource identifier in Keycard Console to your production URL (e.g., https://my-mcp-server.example.com/mcp) — it must use HTTPS
• Set environment variables securely in your hosting platform (KEYCARD_ZONE_ID or KEYCARD_ZONE_URL, KEYCARD_CLIENT_ID, KEYCARD_CLIENT_SECRET, PORT) — never commit secrets to source control

Tip

For infrastructure-as-code deployments, use the Keycard Terraform Provider to programmatically configure resources and applications.