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.

• 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

pip install keycardai-mcp-fastmcp fastmcp

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

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

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
   • TypeScript
   • Go

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

3. Click Create

Create a .env file in your project root:

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

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

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

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()

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

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",
  requireBearerAuth({ issuers: ZONE_URL }),
  (req, res) => {
    res.json({
      message: "Hello from Keycard!",
      authenticated: true,
    });
  },
);

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

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))
}

1. Start the server

   • Python
   • TypeScript
   • Go

   python -m my_server

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

Your MCP server is now protected — every tool call is tied to a verified user, scoped by policy, and logged for audit.

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