MCP Server

Location: apps/mcp

Overview

This application is a specialized Resource Server built with FastMCP. It is designed to expose "tools" that can be called by AI agents. It serves as a practical example of how a non-Hono, RPC-style server can integrate into the project's authentication architecture by consuming JWTs.

Key Features

Purpose-Built for AI: Designed to expose "tools" (RPC-style functions) that AI agents can call.
Lightweight: Minimalist and focused on performance.
JWT Consumer: Demonstrates how a non-Hono server can validate JWTs issued by the auth server.

Project Structure

The server's logic is primarily contained in apps/mcp/src/index.ts. It defines:

An authenticate function that extracts the JWT from the Authorization header.
A series of "tools" that can be called by clients.
A canAccess guard on protected tools to ensure a valid JWT is present.

Core Patterns

Tool-Level Authentication

Unlike the api server, which uses middleware to protect entire routes, the mcp server demonstrates a more granular, tool-level authentication pattern.

Each tool definition can include a canAccess function. This function receives the authentication data (in this case, the session data containing the JWT) and returns true or false to grant or deny access.

// From apps/mcp/src/index.ts

// Protected tool: require JWT
server.addTool({
  name: "get_time",
  description: "Get the current server time (requires JWT authentication)",
  // This function acts as a guard for the tool
  canAccess: (auth): boolean => Boolean((auth as SessionData | undefined)?.jwt),
  async execute(_args, { session }) {
    // ... execution logic
  },
});

This pattern is useful when a single server needs to expose both public and private tools.

A Second JWT Consumer

While the mcp server itself doesn't perform the JWT validation (it delegates that to the tools it calls, like handleGetTime), it demonstrates the client-side of the pattern: it expects a JWT and passes it along. This reinforces the decoupled architecture, showing that any service, regardless of its framework, can participate in the authentication model as long as it understands how to handle a Bearer Token.

Environment Variables

This server's environment variables are validated by src/env.ts. Refer to apps/mcp/.env.example for a template.

MCP_SERVER_PORT: The port the server will run on (e.g., 7411).
RESOURCE_API_URL: The base URL of the api server, which this server's tools may call.