# Drive your Bots from Claude Code, Codex or Cursor

> Turn on the local Neoo MCP API, create API keys, connect a coding assistant and see which tools it can use, with the safety rules that apply.

Neoo can run a small **MCP server on your computer** so a coding assistant such as Claude Code, Codex or Cursor can create and drive your Bots in plain language ("create a Bot that summarises my inbox every morning, then run it once"). Your Bots are end-to-end encrypted and live on your computer, so this API is **local**: nothing goes through Neoo's servers.

It is **off by default**.

## Turn it on

1. Open **Settings → Tools → Neoo MCP**.
2. Switch on **Enable the local MCP API**.
3. Keep the default port (**47890**) or pick another one between 1024 and 65535. If the port is busy, Neoo uses the next free one and shows the address it listens on (`http://127.0.0.1:<port>/mcp`). The same address is written to a private file, `bots-mcp.json`, in Neoo's data folder.

The server only listens on `127.0.0.1`. It stops when you switch it off or quit Neoo.

## Create an API key

1. In **API keys**, type a name (for example "Claude Code") and select **Create**.
2. Copy the key right away. It is **shown only once**: Neoo keeps only a SHA-256 fingerprint, so a lost key cannot be recovered. Create a new one instead.
3. Select **Revoke** on a key to cut its access immediately. The list shows when each key was last used.

Use one key per tool so you can revoke them separately.

## Connect a tool

The **Connect a tool** card shows a ready-to-copy configuration for each client. Replace `<your-neoo-mcp-key>` with your key if you copied it after leaving the screen.

**Claude Code**

```bash
claude mcp add --transport http neoo http://127.0.0.1:47890/mcp --header "Authorization: Bearer <your-neoo-mcp-key>"
```

**Codex** (`~/.codex/config.toml`). Codex reads the key from an environment variable, so it is never written in the file:

```toml
[mcp_servers.neoo]
url = "http://127.0.0.1:47890/mcp"
bearer_token_env_var = "NEOO_MCP_KEY"
```

```bash
export NEOO_MCP_KEY="<your-neoo-mcp-key>"
```

If your Codex version does not support HTTP MCP servers, bridge it with a stdio proxy such as `npx mcp-remote http://127.0.0.1:47890/mcp --header "Authorization: Bearer <your-neoo-mcp-key>"`.

**Cursor** (`~/.cursor/mcp.json` or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "neoo": {
      "url": "http://127.0.0.1:47890/mcp",
      "headers": { "Authorization": "Bearer <your-neoo-mcp-key>" }
    }
  }
}
```

If you changed the port, use yours in every snippet.

## Tools

All tools use `snake_case` names. A tool failure is returned as a readable error result (`isError`), never as a protocol error. Every result carries its JSON in both `content[0].text` and `structuredContent`.

| Area | Tools |
|---|---|
| Bots | `list_bots`, `get_bot`, `create_bot`, `update_bot`, `delete_bot`, `send_message`, `get_messages` |
| Routines | `list_routines`, `upsert_routine`, `run_routine_now`, `delete_routine` |
| Webhooks | `list_webhooks`, `create_webhook`, `rotate_webhook`, `delete_webhook` |
| Skills | `list_skills`, `get_skill`, `upsert_skill`, `delete_skill` |
| Data and knowledge | `list_tables`, `db_query`, `db_execute`, `kb_search`, `kb_read`, `kb_propose` |
| Follow-up | `get_monitoring` |

Notes on specific tools:

- **`create_bot`** creates a Bot on this computer in Full Access, like the Bots panel does. You can give a name, role, instructions, provider and model.
- **`delete_bot`** **archives** the Bot (its runs stop and its routines pause). Nothing is erased and you can restore it in the app.
- **`send_message`** sends to the Bot's main chat. With `waitSeconds` (0 to 120) it returns the Bot's final reply if the turn ends in time. Otherwise it returns a `messageId`: call `get_messages` with `afterMessageId` set to it. `get_messages` is bounded (50 messages at most) and paginated with `before` / `afterMessageId`.
- **`upsert_routine`** takes a schedule of kind `interval` (minutes), `cron` (five fields) or `once` (`runAt`, epoch milliseconds). Routines are the ones shown in the Routines tab.
- **Webhooks** need Neoo to be signed in. The secret URL is returned **only** by `create_webhook` and `rotate_webhook`; `list_webhooks` never shows it.
- **`db_query`** is read-only; **`db_execute`** applies the same guards as the Bot's own data tools. Use `scope: "private"` with a `botId`, or `scope: "shared"` for the database shared by all Bots (a `botId` is still needed to write, as the owner of new tables).
- **`kb_propose`** only proposes a page: a person approves it in the Knowledge base view.
- **`get_monitoring`** summarises recent runs, failures, tokens and cost for a Bot.

## Safety guarantees

- **Local only.** The server binds `127.0.0.1`. Requests carrying an `Origin` header (any web page) or a `Host` other than `127.0.0.1:<port>` / `localhost:<port>` are refused, which blocks malicious pages and DNS rebinding.
- **Authenticated.** Every request needs `Authorization: Bearer <key>`. Keys are stored hashed and can be revoked at any time. Bodies are limited to 256 KB and calls are rate-limited (120 per minute per key; repeated bad keys are throttled).
- **Destructive tools need your approval.** `delete_bot`, `delete_routine`, `delete_webhook`, `rotate_webhook` and `delete_skill` do nothing unless called with `confirm: true`. Without it they return an error telling the assistant to ask you first. A well-behaved assistant asks you in the conversation; do not let it set `confirm` on its own.
- **No secrets.** No tool reads the Vault, provider keys, tokens or webhook secrets. Webhook URLs appear once, at creation or rotation.
- **Audit log.** **Recent calls** lists the tool name, time and key of each call. Arguments and contents are never recorded.

## Limits

- **Neoo Cloud Bots are not reachable.** They run on your Cloud machine, not on this computer. `list_bots` only returns Bots hosted here and says so in its `cloud` field; asking for a Cloud Bot returns a clear "not found on this computer" error.
- Neoo must be running with the API switched on. Closing Neoo stops the server.
- Webhook tools need Neoo to be connected to your account; routine tools need Automations to be enabled.
- Team conversations are not exposed.
- The API is stateless: there are no sessions, resources, prompts or notifications, only `initialize`, `tools/list` and `tools/call`.

Source: https://vatoide.com/docs/bots/mcp-api