Index Codex MCP

A self-hosted MCP server that lets a Pebble Index capture notes, queue work, create follow-ups, and open visible Codex threads on your Windows PC.

The cloud server stores requests. It cannot run code. A local runner on your PC claims only explicit execution requests, resolves project names through a private local registry, and opens each request as a visible Codex thread.

How it works

flowchart LR
    I["Pebble Index"] -->|"Bearer token + MCP"| S["Remote MCP server"]
    C["Codex client"] -->|"Separate bearer token + MCP"| S
    S --> D["Postgres"]
    R["Local Windows runner"] -->|"Poll and update tasks"| S
    R -->|"thread/start + turn/start"| A["Codex App Server"]
    A --> W["Registered project worktree or projectless folder"]

The server exposes different tools to Index and Codex. Index can create records but cannot read or update the inbox. Codex can manage the inbox but cannot invoke run_codex_task. The runner uses the Codex token only to claim and update explicit execution requests.

Related MCP server: codex-mcp-server

Tools

enqueue_task always confirms “Queued, not executed.” Only run_codex_task sets the execution-request flag used by the local runner.

Requirements

• Node.js 24

• A Postgres database; the included driver targets Neon Serverless Postgres

• A host for the remote Next.js route; the deployment steps below use Vercel

• Codex CLI installed and signed in on the Windows PC that runs tasks

• A Pebble Index with HTTP MCP server support

• PowerShell 7 for the supplied runner installer

1. Run the MCP server locally

Install dependencies:

npm install

Copy the environment template:

Copy-Item .env.example .env.local

Set these values in .env.local:

Both tokens must contain at least 32 characters. Generate independent random values and never commit them. An authenticated non-browser MCP client may omit Origin; a request that sends Origin must match ALLOWED_ORIGINS exactly.

Apply the migrations and run the development server:

npm run db:migrate
npm run dev

Run the checks in another terminal:

npm run format
npm run typecheck
npm test
npm run build
npm run smoke

The only application route is POST /api/mcp. There is no frontend or public health route.

2. Deploy to Vercel

Install and sign in to the Vercel CLI, then link the project:

vercel link

Add each production variable interactively. Do not include secret values in the command:

vercel env add DATABASE_URL production
vercel env add INDEX_MCP_TOKEN production
vercel env add CODEX_MCP_TOKEN production
vercel env add ALLOWED_ORIGINS production
vercel env add APP_BASE_URL production

Pull the production configuration into the ignored local file, migrate, verify, and deploy:

vercel env pull .env.local --environment=production
npm run db:migrate
npm run format
npm run typecheck
npm test
npm run build
vercel --prod
npm run smoke

If the production origin changes, update APP_BASE_URL before the final smoke test.

3. Connect Pebble Index

In the Pebble app:

1. Create or select a cloud sandbox group.

2. Add an HTTP MCP server named Index Codex MCP.

3. Set the transport to Streamable HTTP.

4. Set the URL to https://<your-domain>/api/mcp.

5. Set Authorization to Bearer <INDEX_MCP_TOKEN>.

6. Connect the server.

7. Select the exposed index_ops prompt.

8. Assign the sandbox to your preferred Index gesture.

Example requests:

• “Capture for Example App: the mobile menu freezes after returning from an event.”

• “Queue a Codex task for Example App to add completion tracking.”

• “Run a Codex task for Example App: fix the mobile navigation bug and run the relevant tests.”

• “Start a new Codex chat with no project: compare two API designs.”

• “Create a follow-up for Example App due 2026-08-10T15:00:00-06:00 to review the release.”

Due dates must use an explicit ISO 8601 timestamp. The server does not interpret phrases such as “next Thursday.”

4. Connect Codex to the inbox

Store the production Codex token in the Windows user environment without printing it:

$secureToken = Read-Host -AsSecureString "Codex MCP token"
$plainToken = [Net.NetworkCredential]::new("", $secureToken).Password
[Environment]::SetEnvironmentVariable("INDEX_CODEX_MCP_TOKEN", $plainToken, "User")
Remove-Variable secureToken, plainToken

Add the server to your Codex configuration:

[mcp_servers.index_codex]
url = "https://<your-domain>/api/mcp"
bearer_token_env_var = "INDEX_CODEX_MCP_TOKEN"
required = true
default_tools_approval_mode = "writes"
enabled_tools = [
  "capture_item",
  "enqueue_task",
  "create_followup",
  "get_inbox",
  "update_task",
  "update_followup"
]

Restart Codex, then verify the connection:

codex mcp list

5. Configure the visible-thread runner

The runner never accepts a folder path from Index. It maps a spoken project name or alias to an exact path stored only on your PC.

Copy the example registry:

Copy-Item scripts/runner-projects.example.json scripts/runner-projects.json

Edit scripts/runner-projects.json:

[
  {
    "name": "Example App",
    "aliases": ["Example", "My app"],
    "path": "C:\\projects\\example-app",
    "worktree": true
  }
]

Each name and alias must be unique after case and punctuation normalization.

• Set worktree to true for a Git repository. The runner creates codex/ring-<task-id> from the repository's current HEAD and leaves the worktree for review.

• Set worktree to false only when Codex should work in that exact folder.

• Omit the project in a ring request to create a new projectless folder under the configured projectless root.

The real registry is ignored by Git so local project names and paths do not enter commits.

Set the runner endpoint for the Windows user:

[Environment]::SetEnvironmentVariable(
  "INDEX_CODEX_MCP_ENDPOINT",
  "https://<your-domain>/api/mcp",
  "User"
)

The runner uses INDEX_CODEX_MCP_TOKEN, which you set in the previous section. Confirm that Codex is signed in:

codex login status

Open a new terminal so it receives the user environment variables. Test the runner without claiming work:

npm run runner:check

Install and start the scheduled task:

npm run runner:install

The Windows Task Scheduler job starts at sign-in and allows only one runner instance. Your computer must remain on, online, and signed in to Codex. Requests remain queued while the runner is offline.

Optional runner variables

Task lifecycle

Tasks follow these state changes:

• queued → in_progress or cancelled

• in_progress → blocked, done, or cancelled

• blocked → in_progress or cancelled

• done and cancelled are final

The runner claims a task with one conditional database update. Two clients cannot claim the same queued task.

Security and privacy

• Index and Codex use separate bearer tokens and receive different tool sets.

• Authentication runs before JSON parsing.

• Requests larger than 64 KiB are rejected.

• Tool schemas reject unknown fields.

• All SQL uses parameters.

• Idempotency keys cannot be reused with different input.

• Audit rows contain a normalized input hash, outcome, record ID, and timing; they do not contain tool input or credentials.

• The cloud server cannot execute code.

• Voice input never becomes a file path or shell command. Only the ignored local project registry contains paths.

• The runner uses Codex App Server with approvalPolicy: never and sandbox: workspace-write.

• The runner prompt forbids pushing, deploying, merging, messaging, deletion, and external-system changes.

• Local workspace paths are not written back to the cloud task record.

• Projectless requests use a fixed local root, not a caller-provided path.

No secret scanner can prove that arbitrary note text contains no credential. Do not dictate or store secrets.

Troubleshooting

Index cannot connect

• Confirm the URL ends in /api/mcp.

• Select Streamable HTTP, not SSE.

• Use Bearer followed by the Index token.

• Confirm the deployment has INDEX_MCP_TOKEN and DATABASE_URL.

• Check Vercel function logs for safe error codes. Logs intentionally omit request input and tokens.

runner:check fails

• Open a new terminal after setting user environment variables.

• Confirm INDEX_CODEX_MCP_ENDPOINT uses HTTPS, unless it points to localhost.

• Confirm INDEX_CODEX_MCP_TOKEN matches the deployed CODEX_MCP_TOKEN.

• Run codex login status.

• Confirm every path in runner-projects.json exists.

A task stays queued

• Confirm the scheduled task Index Codex MCP Runner is running.

• Run npm run runner:check.

• Confirm the project name or alias matches the local registry.

• Check the scheduled-task history or run npm run runner in a terminal for structured event names.

A task becomes blocked

Open the visible Codex thread. If the runner created a Git worktree, inspect the configured worktree root. Failed workspaces remain available for review.

Development

npm run format
npm run typecheck
npm test
npm run build

The test suite covers authentication boundaries, tool visibility, strict input, idempotency, task state changes, project registry resolution, runner task selection, and visible-thread request parameters.

See docs/architecture.md for the runtime design and invariants.

Limits

• The supplied runner installer supports Windows only.

• The Codex App Server interface may change; pin and test Codex CLI updates before unattended use.

• One runner processes one task at a time.

• The server has no frontend, OAuth provider, search UI, delete tool, or automatic deployment step.

• Worktrees start from the registered repository's current HEAD; the runner does not fetch or choose a remote branch.

Licence

MIT