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

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:

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

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

{
  "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.

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.