feat(mcp): add native /mcp for cost control

[alex-alecu]

Summary

Kilo now has a standard MCP endpoint for admins to read their own Kilo stats without setting custom headers. It uses the normal browser sign-in and OAuth flow, then gives MCP clients one read-only stats tool. Access is limited to Kilo org admins for the first rollout, and each query can only look at the signed-in user's last 60 days.

Verification

1. Start the web app with MCP gateway keys.
2. Call /mcp without a token and confirm it returns a 401 OAuth challenge.
3. Register an MCP client, approve access as a Kilo org admin, exchange the code for a token, then call tools/list.
4. Call query_kilo_dataset for microdollar_usage with a count metric and confirm it returns a structured result.

Visual Changes

N/A

Reviewer Notes

This adds new OAuth tables and keeps the first rollout behind the Kilo org admin gate. The MCP tool returns aggregate and time series stats only, not raw rows.

[kilo-code-bot]

Code Review Summary

Status: 4 Issues Found | Recommendation: Address before merge

Fix these issues in Kilo Cloud

Overview

Severity	Count
CRITICAL	0
WARNING	4
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/app/api/mcp-gateway/oauth/token/route.ts	35	Native refresh-token requests are misrouted when resource is omitted.
apps/web/src/app/mcp/route.ts	73	Verifier failures are flattened into 401 invalid_token, hiding insufficient_scope and forbidden cases.
apps/web/src/lib/kilo-datasets/query.ts	517	Boolean(value) can flip string-backed Postgres booleans to true.
packages/mcp-gateway/src/native-resource.ts	5	The native MCP resource/audience is hard-coded to production.

Files Reviewed (31 files)

• .specs/mcp-gateway-auth.md - 0 issues
• apps/web/package.json - 0 issues
• apps/web/src/app/.well-known/oauth-authorization-server/oauth/authorize/route.ts - 0 issues
• apps/web/src/app/.well-known/oauth-authorization-server/route.ts - 0 issues
• apps/web/src/app/.well-known/oauth-protected-resource/mcp/route.ts - 0 issues
• apps/web/src/app/.well-known/oauth-protected-resource/route.ts - 0 issues
• apps/web/src/app/api/mcp-gateway/oauth/authorize/route.test.ts - 0 issues
• apps/web/src/app/api/mcp-gateway/oauth/authorize/route.ts - 0 issues
• apps/web/src/app/api/mcp-gateway/oauth/token/route.ts - 1 issue
• apps/web/src/app/mcp/route.test.ts - 0 issues
• apps/web/src/app/mcp/route.ts - 1 issue
• apps/web/src/lib/kilo-datasets/contracts.ts - 0 issues
• apps/web/src/lib/kilo-datasets/query.test.ts - 0 issues
• apps/web/src/lib/kilo-datasets/query.ts - 1 issue
• apps/web/src/lib/mcp-gateway/services.ts - 0 issues
• apps/web/src/lib/mcp-gateway/token-service.ts - 0 issues
• apps/web/src/lib/mcp/kilo-dataset-server.ts - 0 issues
• apps/web/src/lib/native-mcp/oauth/native-authorization-service.ts - 0 issues
• apps/web/src/lib/native-mcp/oauth/native-token-service.ts - 0 issues
• apps/web/src/lib/native-mcp/oauth/native-token-verifier.test.ts - 0 issues
• apps/web/src/lib/native-mcp/oauth/native-token-verifier.ts - 0 issues
• apps/web/src/lib/user/index.test.ts - 0 issues
• apps/web/src/lib/user/index.ts - 0 issues
• packages/db/src/migrations/0167_perpetual_hulk.sql - 0 issues
• packages/db/src/migrations/meta/0167_snapshot.json - 0 issues
• packages/db/src/migrations/meta/_journal.json - 0 issues
• packages/db/src/schema.ts - 0 issues
• packages/mcp-gateway/src/index.ts - 0 issues
• packages/mcp-gateway/src/native-resource.ts - 1 issue
• pnpm-lock.yaml - 0 issues
• scripts/verify-drizzle-bootstrap.sh - 0 issues

---

_{Reviewed by gpt-5.4-20260305 · Input: 181K · Output: 19.9K · Cached: 2.4M}

_{Review guidance: REVIEW.md from base branch main}

[alex-alecu]

Manual test passed.

Tested:

• Unauthenticated /mcp challenge and mismatched Origin rejection.
• OAuth discovery metadata for the native MCP resource.
• Fake admin sign-in, dynamic OAuth client registration, native MCP consent approval, and authorization-code token exchange.
• Authenticated MCP initialize, tools/list, and query_kilo_dataset aggregate/timeseries calls.
• query_kilo_dataset rejection for a range over 60 days.

Verified:

• /mcp returned the expected mcp:access OAuth challenge and exposed query_kilo_dataset after native bearer auth.
• Dataset results were structured, scoped to me, and returned the seeded local microdollar_usage aggregate/timeseries rows.
• Postgres contained the registered OAuth client, consumed native authorization code, native refresh token, Kilo org admin membership, and user-scoped usage rows.