MCP server

Audited operations and actual coverage

This source version adds 80 audited operations across SDK, CLI and MCP. Installed npm versions and hosted enablement must be checked separately.

Coverage: contacts, tasks, tickets, inbox assignment/status/labels/internal notes and separate text sending; AI drafts/configuration/reviewed text knowledge/channels/tests/readiness/publish; manual orders/status/payment/fulfillment; products/categories; contact status/stage/assignment/tags/custom fields; automation inspection/inactive draft/dry simulation/pause/approved activation; campaign audience estimates/drafts/pause/cancel and approved send/resume/schedule. The 553-route inventory is discovery metadata, not executable full dashboard parity.

SDK: describeOperations(), prepareOperation(id, input, idempotencyKey), executeOperation(id, input, { idempotencyKey, confirmation }). CLI: operations list/inspect/preview/run with --input, --idempotency-key and --confirm. MCP: operations_list, operation_inspect, operation_preview, operation_execute; messages use message_send and activation uses lifecycle_activate; campaign delivery uses campaign_send or campaign_schedule. CLI sending uses messages send after previewing inbox.message.send.

Show the exact preview and obtain explicit user approval before a mutation. The confirmation hash binds normalized input and key; it does not prove human approval. Retain the same idempotency key for recovery. No automatic retries. Existing tenant, role, scope and plan gates apply. OAuth write scopes require new explicit consent and start unchecked; old grants do not gain permissions.

AI tests and knowledge processing may consume credits. Publishing and channel assignment can affect live replies. Sending requires approval of contactId, channelId/type and complete text; the server rechecks the target. Inbox media/template sends, entity deletion, arbitrary HTTP, billing and platform administration are not exposed. Campaign template delivery and scheduling require a separate approved frozen audience/content/sender/time snapshot. Order and contact tag changes may trigger configured automation; custom fields replace the entire map; payment updates do not charge a provider. Refunds/cancellation and full campaign/automation coverage remain excluded.

@inboxychat/mcp is a Model Context Protocol server that runs on your computer over STDIO. Your AI client starts it with npx; it reads Inboxy through the public API v1 with your key.

Needs Node.js >= 20.3. Nothing to install globally: the client runs the package with npx. To check it starts:

INBOXY_API_KEY="inboxy_YOUR_KEY" npx -y @inboxychat/mcp

1. Sign in to Inboxy as a company admin and open Developers → API keys in the dashboard (/developer-center/keys).
2. Choose "Create an API key" and give the key a name you will recognise (for example "Claude on my laptop").
3. Tick only the scopes you need. There is no default set: a key without scopes cannot be created. The read tools need the ":read" scopes (contacts:read, orders:read, ...).
4. Pick an expiry: 30, 90 (default), 180 or 365 days, or never. The default is 90 days.
5. Copy the key when it is shown. It starts with "inboxy_". Store it in a secret manager or the OS keychain, never in a repository.

Where the server looks for the key

1. INBOXY_API_KEY in the client config "env" (INBOXY_API_URL optional).
2. The OS keychain entry written by inboxy auth login (CLI). INBOXY_PROFILE picks the profile.
3. Only on machines without a keychain: the 0600 config file written by inboxy auth login --store file.

npm i -g @inboxychat/cli
inboxy auth login        # opens the browser (or paste a key when piped)

ChatGPT (hosted MCP)

ChatGPT cannot start a local process. Use the hosted server. You must be a company admin; consent opens in Inboxy and never shares a raw API key with OpenAI.

1. In ChatGPT: Settings → Apps & Connectors (or Custom MCP) → add a new connector.
2. Server URL: https://api.inboxy.chat/mcp (OAuth is discovered from the well-known metadata on the same host).
3. Approve the consent screen in Inboxy as a company admin, then ask: "Which Inboxy company am I connected to?"
4. Revoke any time under Developers → MCP → Connected AI apps.

https://api.inboxy.chat/mcp

claude.ai (hosted MCP)

Same hosted URL as ChatGPT. Claude.ai connectors use OAuth; the Inboxy consent page shows the requested read scopes before anything is granted.

1. In Claude.ai: Settings → Connectors → Add custom connector / MCP server.
2. Paste https://api.inboxy.chat/mcp, complete OAuth, approve as company admin.
3. Try: "List my five oldest pending orders." Claude should call orders_list.

https://api.inboxy.chat/mcp

Claude Code

Hosted server: add the URL, then type /mcp inside Claude Code, pick inboxy and sign in; approve the consent screen in Inboxy as a company admin. Local server: store the key with inboxy auth login and add the npx command.

claude mcp add --transport http inboxy https://api.inboxy.chat/mcp

claude mcp add inboxy -- npx -y @inboxychat/mcp

claude mcp add inboxy -e INBOXY_API_KEY="$INBOXY_API_KEY" -- npx -y @inboxychat/mcp

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"],
      "env": { "INBOXY_API_KEY": "${INBOXY_API_KEY}" }
    }
  }
}

Claude Desktop

Settings → Developer → Edit Config, add the server to claude_desktop_config.json, then restart Claude Desktop. Claude Desktop does not expand ${VAR}: store the key with inboxy auth login and leave out "env", or put the key in "env" and keep the file private.

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"]
    }
  }
}

Codex (OpenAI Codex CLI)

Codex connects to the hosted server over HTTPS and signs in with OAuth in your browser; approve the consent screen in Inboxy as a company admin. Needs a recent Codex CLI: update it if --url or codex mcp login is not recognised.

codex mcp add inboxy --url https://api.inboxy.chat/mcp
codex mcp login inboxy

[mcp_servers.inboxy]
url = "https://api.inboxy.chat/mcp"

codex mcp add inboxy --env INBOXY_API_KEY="$INBOXY_API_KEY" -- npx -y @inboxychat/mcp

Gemini CLI

Gemini CLI connects to the hosted server over HTTPS. After adding it, start gemini and run /mcp auth inboxy to sign in with OAuth; approve the consent screen in Inboxy as a company admin.

gemini mcp add --transport http inboxy https://api.inboxy.chat/mcp

{
  "mcpServers": {
    "inboxy": {
      "httpUrl": "https://api.inboxy.chat/mcp"
    }
  }
}

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"],
      "env": { "INBOXY_API_KEY": "$INBOXY_API_KEY" }
    }
  }
}

Cursor

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"]
    }
  }
}

VS Code

{
  "inputs": [
    { "type": "promptString", "id": "inboxy-key", "description": "Inboxy API key", "password": true }
  ],
  "servers": {
    "inboxy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"],
      "env": { "INBOXY_API_KEY": "${input:inboxy-key}" }
    }
  }
}

1. Create a key with the read scopes you want.
2. Store it: inboxy auth login.
3. Add the server to your client (above).
4. Ask: "Which Inboxy company am I connected to?" The client calls company_get.

Questions to try

• "How many orders are still pending? List the five oldest." (orders_list)
• "Find the customer with phone 9665... and show their orders." (contacts_search, orders_list)
• "Summarise today’s unread WhatsApp conversations." (conversations_list, conversation_messages)
• "How close am I to my plan limits?" (usage_get)
• "Is product SKU ABC-1 in stock?" (products_search)

Several companies (agencies)

Store one profile per company with inboxy auth login --profile client-a, then add one server per company with INBOXY_PROFILE set.

claude mcp add inboxy-client-a -e INBOXY_PROFILE=client-a -- npx -y @inboxychat/mcp
claude mcp add inboxy-client-b -e INBOXY_PROFILE=client-b -- npx -y @inboxychat/mcp

Tools

Lists use cursor paging: limit 1-50 (default 20); pass meta.nextCursor back as cursor. operation_execute is marked potentially destructive; discovery and preview are read-only.

Environment

• Writes are limited to the audited operation catalog with explicit confirmation.
• One API read per tool call, and nothing else.
• The same rate limits as the REST API apply to the key.
• HTTPS only (http for localhost); redirects are refused; the key never appears in results, errors or logs.
• Cancelling a request in the client aborts the HTTP request.

Run inboxy doctor to check the same key and URL the server uses.