Claude Code Local Tooling

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• apps/api/spec/bio.md
• apps/api/spec/auth.md
• apps/api/spec/feedback.md
• apps/api/test/infrastructure/http/server.integration.test.ts
• apps/api/test/infrastructure/http/mcp.router.test.ts

Claude Code Local Tooling provides the Model Context Protocol (MCP) infrastructure required for AI assistants to interact with Thoth services. It exposes local capabilities and remote API features through standardized tools, enabling an LLM to perform actions like managing biographies, storing memories, or submitting feedback.

The system relies on a .mcp.json configuration to wire up MCP servers and utilizes specific environment variables for authentication. The core of this tooling lives within the apps/api workspace, providing a bridge between the Thoth backend and Claude's execution environment.

Sources: README.md:12-14, CLAUDE.md:18-20

Architecture and Transport

Thoth implements the MCP "streamable HTTP" transport. The API server mounts MCP functionality at specific endpoints to handle JSON-RPC messages from the Claude client.

Endpoints

The server facilitates two primary mounting points for MCP traffic:

• POST /mcp: The bare endpoint used for tool discovery and private tool calls.
• POST /mcp/:handle: A public endpoint that passes a specific site :handle to the underlying tools.

Sources: apps/api/test/infrastructure/http/server.integration.test.ts:117-123, apps/api/test/infrastructure/http/mcp.router.test.ts:46-52

Request Flow

The following diagram illustrates how a Claude client interacts with the Thoth MCP server:

Tool Categories

Tools are divided into public and private categories. Public tools are accessible anonymously, while private tools require user authentication.

Tool Name	Scope	Purpose	Description
get_bio	Public	Bio Management	Returns name, headline, and about for a handle.
create_bio	Private	Bio Management	Creates a new bio for the authenticated user.
update_bio	Private	Bio Management	Updates the existing bio of the authenticated user.
submit_feedback	Public	Communication	Persists a freeform message from a visitor.
remember	Private	Memory	Stores user-scoped data.
recall	Private	Memory	Retrieves user-scoped data.

Sources: apps/api/spec/bio.md:11-13, apps/api/spec/feedback.md:11-13, apps/api/spec/auth.md:13-14

Authentication and Security

Thoth uses OAuth 2.1 via Better Auth to secure private MCP tools. When a client attempts to call a private tool without a valid token, the server returns a 401 response with a WWW-Authenticate header.

Authentication Flow

1. Initial Call: Client sends a tools/call for a private tool.
2. Challenge: Server validates the tool name against a PrivateToolNames set and returns 401 if no valid bearer token exists.
3. Login: The client performs an OAuth dance with Better Auth, which federates to GitHub.
4. Retry: The client retries the call with a JWT in the Authorization: Bearer header.
5. Validation: verifyBearer validates the JWT and returns a Principal containing userId and scopes.

Sources: apps/api/spec/auth.md:16-28, apps/api/test/infrastructure/http/server.integration.test.ts:167-175, apps/api/test/infrastructure/http/mcp-auth.middleware.test.ts:60-70

Security Rules

• Private tool calls directed to /mcp/:handle return a 404 to prevent handle-spoofing or unauthorized access on public paths.
• Every user-scoped row in the database carries a userId, and queries are filtered by this ID.
• Schema validation for tool inputs (e.g., handle format, string lengths) occurs before the handler executes.

Sources: apps/api/spec/auth.md:34-35, apps/api/spec/bio.md:15-18, apps/api/test/infrastructure/http/server.integration.test.ts:182-195

Local Configuration

For local development and usage with Claude Code, environment variables and configuration files must be established.

Environment Setup

The GitHub MCP server integration specifically requires a token for operation:

export GITHUB_TOKEN=$(gh auth token)

Sources: README.md:16-20

MCP Context Structure

When tools are registered, they receive an McpRequestContext which provides access to the request environment:

• handle: Extracted from the URL path if present.
• principal: The authenticated user identity (userId, scopes) provided by the auth middleware.

Sources: apps/api/test/infrastructure/http/mcp.router.test.ts:35-43, apps/api/test/infrastructure/http/mcp.router.test.ts:88-100

Summary

Claude Code Local Tooling in Thoth implements the Model Context Protocol to bridge AI capabilities with local project services. By utilizing a streamable HTTP transport, federated GitHub authentication, and a clear separation between public and private tools, the system provides a secure and extensible interface for AI-driven development and interaction.