Add Auth to Custom MCP

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 and TypeScript.

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

pip install keycardai-fastmcp fastmcp

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

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

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

3. Click Create

4. In Zone Settings, turn off “Require invitation to sign in to this zone” so users can self-register when they authenticate for the first time.

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

import os

from fastmcp import FastMCP
from keycardai.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 { 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_ZONE_URL ?? "https://<your-zone-id>.keycard.cloud";
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 }),
  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);
  },
);

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

1. Start the server

   • Python
   • TypeScript

   python server.py

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. Keycard will prompt you to sign in to your zone. This is a separate account from your Keycard Console login. If it’s your first time, click Sign up to create one.
   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.