# 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.

> [!WARNING]
> This project can start unattended coding work on your computer. Read the security model, register only folders you trust, and keep the runner's Codex sandbox enabled.

## How it works

```mermaid
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.

## Tools

| Tool              | Index | Codex | Effect                                                  |
| ----------------- | :---: | :---: | ------------------------------------------------------- |
| `capture_item`    |  Yes  |  Yes  | Store exact note text and an optional project           |
| `enqueue_task`    |  Yes  |  Yes  | Queue work without executing it                         |
| `create_followup` |  Yes  |  Yes  | Create an open follow-up                                |
| `run_codex_task`  |  Yes  |  No   | Request a visible local Codex thread                    |
| `get_inbox`       |  No   |  Yes  | Read recent captures, active tasks, and open follow-ups |
| `update_task`     |  No   |  Yes  | Claim or update a task through valid state changes      |
| `update_followup` |  No   |  Yes  | Mark a follow-up done or cancelled                      |

`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:

```powershell
npm install
```

Copy the environment template:

```powershell
Copy-Item .env.example .env.local
```

Set these values in `.env.local`:

| Variable          | Purpose                                                                          |
| ----------------- | -------------------------------------------------------------------------------- |
| `DATABASE_URL`    | Pooled Postgres connection string                                                |
| `INDEX_MCP_TOKEN` | Private bearer token used only by Index                                          |
| `CODEX_MCP_TOKEN` | Different private bearer token used by Codex and the runner                      |
| `ALLOWED_ORIGINS` | Comma-separated exact browser origins; leave empty to reject all present origins |
| `APP_BASE_URL`    | Server origin used by the smoke test                                             |

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:

```powershell
npm run db:migrate
npm run dev
```

Run the checks in another terminal:

```powershell
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:

```powershell
vercel link
```

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

```powershell
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:

```powershell
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:

```powershell
$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:

```toml
[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:

```powershell
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:

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

Edit `scripts/runner-projects.json`:

```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:

```powershell
[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:

```powershell
codex login status
```

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

```powershell
npm run runner:check
```

Install and start the scheduled task:

```powershell
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

| Variable                       | Default                                      | Purpose                              |
| ------------------------------ | -------------------------------------------- | ------------------------------------ |
| `INDEX_CODEX_PROJECTS_FILE`    | `scripts/runner-projects.json`               | Private project registry path        |
| `INDEX_CODEX_CODEX_HOME`       | `%USERPROFILE%\.codex`                       | Codex state used for visible threads |
| `INDEX_CODEX_WORKTREES_ROOT`   | `%USERPROFILE%\.codex\worktrees\index-codex` | Isolated Git worktrees               |
| `INDEX_CODEX_PROJECTLESS_ROOT` | `%USERPROFILE%\Documents\Codex\Index`        | New chats without a project          |
| `INDEX_CODEX_CODEX_COMMAND`    | `codex`                                      | Codex executable name or full path   |

## 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

```powershell
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](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](LICENSE)