feat: add MCP server with OAuth 2.1 authentication

[volod-vana]

Summary

• Adds MCP (Model Context Protocol) server for AI tool integration — exposes user data as resources and tools
• Adds OAuth 2.1 (PKCE + RFC 7591 dynamic client registration) to protect the /mcp endpoint
• Identity verification delegates to Account Portal (account.vana.org) — user signs "vana-master-key-v1", server recovers wallet via EIP-191 and checks ownership before issuing tokens

MCP capabilities

• Resources: list scopes, read scope data (latest or specific version)
• Tools: search_files (search across scopes), list_versions (version history)

OAuth endpoints

• /.well-known/oauth-authorization-server — discovery metadata
• /.well-known/oauth-protected-resource — resource metadata
• POST /register — dynamic client registration
• GET /authorize → redirects to Account Portal
• GET /oauth/callback — receives wallet proof, issues auth code
• POST /token — code exchange (PKCE) and refresh

How auth works

1. MCP client hits /mcp → gets 401 with WWW-Authenticate
2. Discovers OAuth, registers dynamically, initiates PKCE flow
3. User authenticates via Account Portal (Privy), signs masterKeySig
4. Server recovers wallet, checks ownership, issues tokens
5. Bearer token on all /mcp requests

Security

• PKCE required (S256 only), auth codes single-use (5min TTL)
• Access tokens 1h expiry, refresh token rotation
• Wallet verified via EIP-191 recovery of "vana-master-key-v1"
• Owner wallet → full access; unknown → denied

Test plan

• npm run build passes
• All 462 existing tests pass
• curl POST /mcp → 401 with WWW-Authenticate
• GET /.well-known/oauth-authorization-server → valid metadata
• End-to-end with Claude custom connector

Depends on: vana-com/vana-connect PR for Account Portal HTTPS redirect support

🤖 Generated with Claude Code

[github-actions]

Codex Review

Findings

1. Security: MCP endpoint exposes all personal data without auth.
   /mcp is mounted whenever serverOwner is present, but there is no auth guard at all. Anyone who can reach the server can call MCP tools/resources (get_file, list_files, search_files, vana://grants, etc.) and exfiltrate data. CORS is *, so this is also callable from any browser origin. Add the same owner/dev-token auth used on /v1/*, or require a signed token/header for MCP requests.
   Files: packages/server/src/app.ts:134, packages/server/src/routes/mcp.ts:13, packages/mcp/src/resources/files.ts:10, packages/mcp/src/resources/grants.ts:5, packages/mcp/src/tools/get-file.ts:22.

2. Correctness/DoS risk: search_files reads full JSON for up to 500 scopes per request.
   The tool loads and stringifies entire latest payloads in-process, per scope, until it finds maxResults. On large datasets this can be very slow, block the event loop, and allow resource exhaustion. Consider enforcing a tighter scan limit, adding size/time caps, or streaming/indexing for search.
   File: packages/mcp/src/tools/search-files.ts:33.

3. Protocol correctness risk: new MCP server instance per request.
   mcpRoute constructs a new McpServer and WebStandardStreamableHTTPServerTransport on every HTTP request. If MCP expects session continuity (e.g., follow-up calls by mcp-session-id), you will lose state and potentially break multi-step interactions. Consider caching per session or keeping a single server instance bound to the route.
   File: packages/server/src/routes/mcp.ts:13.

Missing tests

1. Auth-required access for /mcp (unauthenticated should be denied).
   Files: packages/server/src/app.ts:134, packages/server/src/routes/mcp.ts:13.

2. MCP session continuity across multiple requests (initialize → tool call).
   File: packages/server/src/routes/mcp.ts:13.

3. search_files behavior/perf on large datasets (limits, timeouts, or graceful failure).
   File: packages/mcp/src/tools/search-files.ts:33.

If you want, I can propose an auth middleware placement and minimal test cases for MCP.

[volod-vana]

Codex review raised 3 concerns, heres where we landed:

1. No auth on MCP endpoint - addressed. Full OAuth 2.1 with PKCE, wallet-based identity verification via EIP-191 signature recovery. Bearer token required for all MCP requests when server owner is configured.
2. search_files DoS risk (500 scopes full scan) - not addressed, acceptable for now. Personal server handles small datasets, this wont be a problem in practice. Will revisit if we see performance issues.
3. New MCP server instance per request - by design. Using stateless WebStandardStreamableHTTPServerTransport without session continuity. Fine for current use case where we dont need subscriptions or server-to-client notifications.

Minor things to follow up on separately:

• client_secret is generated but never verified at /token endpoint - not exploitable because PKCE is mandatory but its misleading. Should either validate it or change auth method to "none"
• In-memory OAuth state (tokens, clients) doesnt survive server restart - clients need to re-auth. Acceptable for now
• No cleanup for expired tokens / stale pending auths - minor memory leak over long-running sessions