AIOS MCP

A remote MCP (Model Context Protocol) server that turns Hua's AIOS Kernel conventions into callable tools instead of prompt-only rules. Deployed on Vercel, separate from mcp-drive-server. Personal, single-user use only.

Hard-scoped to ONE canonical Google Doc — the PROJECT-MANAGEMENT portfolio doc — configured via AIOS_PORTFOLIO_DOC_ID. Tools never accept an arbitrary file_id, so a write from this server can never land on the wrong document.

Tools exposed at /api/mcp:

• aios_list_sections — read-only, lists the doc's top-level section headings

• aios_get_section — read-only, returns one section's full text (Focus Now, Registry, Cross-AI Recovery Queue, Backlog, Archived, ...)

• aios_find_and_replace — guarded in-place find/replace (refuses on 0 or >1 matches unless explicitly allowed), for editing an existing Registry row/field

• aios_append_to_section — inserts new text at the end of a named section, for adding a new Registry row / Recovery Queue entry / Backlog item

0. Reuse existing Google credentials — no new Cloud Console setup

This server reuses the SAME Google OAuth Client ID / Secret / Refresh Token that mcp-drive-server already has (see that project's Google Cloud.txt in Drive folder "MCP Server for Claude"). That refresh token already carries the https://www.googleapis.com/auth/drive scope, which covers the Docs API documents.get / documents.batchUpdate calls used here — no new scope, no new OAuth Client, no re-authorization needed.

Related MCP server: google-mcp

1. Environment variables

See .env.example. You need:

• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REFRESH_TOKEN — copy from mcp-drive-server's Vercel project settings

• AIOS_PORTFOLIO_DOC_ID — the canonical PROJECT-MANAGEMENT Google Doc's file ID

• MCP_AUTH_TOKEN — generate a new one: openssl rand -hex 32. This is separate from mcp-drive-server's token — a leak of one doesn't expose the other.

2. Local setup and test

npm install
cp .env.example .env.local
# fill in .env.local with the values from step 1
npm run typecheck   # tsc --noEmit
npm run dev         # starts http://localhost:3000

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector@latest http://localhost:3000/api/mcp

3. Deploy

Push to a new GitHub repo (aios-mcp), then import into a NEW Vercel project (do not reuse the mcp-drive-server project) and set the environment variables from step 1 in Vercel project settings before the first deploy.

Expected final MCP endpoint: https://<your-project>.vercel.app/api/mcp

4. Connecting to a client

v1 uses a plain static Bearer-token check (lib/auth.ts) — simpler than mcp-drive-server's OAuth 2.1 compatibility layer. This works directly with any client that lets you set a fixed Authorization: Bearer <token> header (MCP Inspector, many custom-connector "Advanced settings" screens, ChatGPT API-key auth).

If you need to connect this to a client that only offers OAuth Client ID/Secret fields (no raw bearer field) — e.g. Claude's custom-connector UI — copy lib/oauth.ts and the /api/oauth/* routes from the mcp-drive-server repo. They are generic OAuth 2.1 PKCE helpers, not Drive-specific, and drop in unchanged; ask for that as a fast-follow if/when it's needed.

Human Approval Gate

Per AIOS Core §5.12, this repo/deployment is an architecture change and its first real Production promotion (pointing it at the live canonical doc from a real client) needs Hua's explicit approval before regular use, same as any other AIOS production deployment.