@axid-dev/mcp-server

MCP server for axid bot development. Connect Claude Desktop / Cursor / any MCP client to spin up bots, compose block messages, and dogfood your workspace from the editor.

Why

Building a bot for a chat platform usually means:

1. Generating an API key in a settings page.
2. Reading 10+ pages of docs to figure out the message JSON shape.
3. Writing boilerplate for auth, webhooks, message dispatch.
4. Trial-and-erroring schema mistakes against a live API.

This MCP server collapses all of that into 5 high-level tools your AI calls on your behalf.

| Tool | What it does | |---|---| | setup_axid_bot | Create a bot user + issue an API key in your workspace. | | scaffold_bot_project | Return a starter bot project for Node / Cloudflare Workers / Vercel. | | compose_block_message | Validate a Tiptap doc with block_* nodes against the same SSoT the server uses — catch errors locally. | | send_test_message | POST a message to a channel. Closes the AI → message round-trip. | | inspect_workspace | Read-only snapshot: workspace identity, channels, members, the bot's own status. |

The 11 stable block schemas (text, heading, quote, divider, image, link_unfurl, callout, alert_banner, button_group, linear_issue_card, github_pr_card) are documented inline in the compose_block_message tool description, so your AI client has everything it needs without an extra resource fetch.

Install

The server is invoked via npx, so you don't install it directly — you just point your MCP client at it.

npx @axid-dev/mcp-server

Requirements: Node 20+.

Configure

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "axid": {
      "command": "npx",
      "args": ["-y", "@axid-dev/mcp-server"],
      "env": {
        "AXID_API_KEY": "axid_live_...",
        "AXID_API_BASE_URL": "https://axid.app"
      }
    }
  }
}

Restart Claude Desktop. The 5 axid tools should appear in the tool drawer.

Cursor

Edit ~/.cursor/mcp.json (or use the Settings UI):

{
  "mcpServers": {
    "axid": {
      "command": "npx",
      "args": ["-y", "@axid-dev/mcp-server"],
      "env": {
        "AXID_API_KEY": "axid_live_..."
      }
    }
  }
}

Other MCP clients

Any client that speaks MCP over stdio works. Spawn npx -y @axid-dev/mcp-server as a child process; pass AXID_API_KEY (and optionally AXID_API_BASE_URL) as env.

Get an API key

The first time you use the server you need a workspace admin key:

1. Sign in at https://axid.app.
2. Workspace Settings → API keys → Generate.
3. Copy the axid_live_... value into your MCP client config.

That admin key lets setup_axid_bot create bot users. You can later mint additional bot-scoped keys without re-using the admin key.

Environment variables

| Var | Required | Default | Notes | |---|---|---|---| | AXID_API_KEY | yes (or per-call) | — | Bearer token for the bot API. Each tool also accepts an api_key argument that overrides this. | | AXID_API_BASE_URL | no | https://axid.app | Override for self-hosted or staging. Trailing slashes stripped. |

Example session

A typical end-to-end flow with Claude:

1. You: "Set up an axid bot called release-radar." → Claude calls setup_axid_bot({name: 'release-radar'}). → Returns bot_user_id + api_key + joined channels.

2. You: "Scaffold a Node project for it." → scaffold_bot_project({bot_name: 'release-radar', target_runtime: 'node'}). → Returns files: {...}. Claude writes them to disk via its Edit tool.

3. You: "Make a P0 deploy alert that links to AXD-284 in Linear." → Claude composes the block JSON in its head, then calls compose_block_message({content_json: {...}}). → Validator passes; preview text returned.

4. You: "Send it to #engineering." → Claude calls inspect_workspace({include: ['channels']}) to find the channel id. → Then send_test_message({channel_id: '...', content: '...', content_json: {...}}). → Returns message_id + card_origin: 'bot'.

That's a fully tested bot in five tool calls.

Tool reference

setup_axid_bot

Create a bot user and issue its first API key.

| Param | Type | Notes | |---|---|---| | name | string | Bot display name. | | description | string? | Reserved. | | default_channel_only | boolean? | Auto-join all default channels. Default true. | | api_key | string? | Override env. |

Returns {bot_user_id, api_key, joined_channels, next_steps}. The raw api_key is shown only once — store it in your bot project's .env.

Caller (env or api_key arg) must be a workspace admin/owner.

scaffold_bot_project

Return a starter bot project as a {relativePath: contents} map.

| Param | Type | Notes | |---|---|---| | bot_name | string | Lowercase identifier. Used in package.json name. | | webhook_path | string? | URL path the handler binds to. Default /webhook. | | target_runtime | enum | node | cloudflare-workers | vercel. |

Each runtime ships with package.json, tsconfig.json, an entry file, a messages.ts API client helper, an env example, and a README.

The MCP host (Claude, Cursor) writes the files to disk — this tool only emits the contents.

compose_block_message

Validate a content_json doc before posting.

| Param | Type | Notes | |---|---|---| | content_json | object | Tiptap doc. See the tool description for block_ shape and per-block schemas. | | available_blocks | string[]? | Restrict allowed blocks. Default: all 11 stable blocks. |

On success: {valid: true, content_json, preview, card_origin, mentioned_user_ids}. On failure: {valid: false, error_code, message, hint} plus isError: true.

Validation is the same code path the bot API uses server-side, so a passing compose_block_message guarantees a successful send_test_message (modulo network/rate-limit issues).

send_test_message

POST a message to a channel.

| Param | Type | Notes | |---|---|---| | channel_id | UUID | Target channel. | | content | string | Plain-text fallback (required by API). | | content_json | object? | Block message JSON. | | thread_id | UUID? | Reply within a thread. | | api_key | string? | Override env. |

Returns {message_id, channel_id, user_id, card_origin, content_text, sent_at}.

inspect_workspace

Read workspace + channel + member + bot status.

| Param | Type | Notes | |---|---|---| | include | array | Subset of ['channels', 'members', 'bot_status']. Default ['channels', 'bot_status']. | | api_key | string? | Override env. |

Returns {workspace, channels?, members?, bot_status?}. Channels and members are capped at 50 per call.

Security

• Tool invocations include the API key in transit only — the MCP server never logs it.
• Prefer the AXID_API_KEY env to per-call api_key arguments. Per-call keys can leak into transcript context.
• The bot API issues distinct keys for each agent. Compromise of a bot key does not expose admin operations on the workspace.

Development

This package lives inside the axid monorepo (path: packages/mcp-server). To work on it locally:

git clone https://github.com/axid-app/axid
cd axid
pnpm install
pnpm --filter @axid-dev/mcp-server build

The build step uses tsup to bundle workspace deps (@app/blocks, @app/shared) inline, then mirrors src/templates/ to dist/templates/. The published tarball ships only dist/.

Run a quick smoke test against the built binary:

node packages/mcp-server/dist/bin.js < /dev/null
# stderr: [axid-mcp-server] connected via stdio

License

MIT.