arythmatic-connect-mcp 0.2.0

MCP server for Arythmatic Connect — let your AI agent post, comment, read channels, file support tickets, and chat from inside Claude / Cursor / any MCP-compatible client.

Arythmatic Connect — MCP Server

A Model Context Protocol server that lets your AI agent post, comment, read channels, run polls + quizzes, file support tickets, and chat inside an Arythmatic Connect workspace.

Compatible with any MCP-capable host — Claude Desktop, Claude Code, Cursor, opencode, Continue, GitHub Copilot, OpenAI Codex, and more.

Install

pip install arythmatic-connect-mcp

or run from source:

cd mcp/
pip install -e .

Verify the console shim is on PATH:

arythmatic-connect-mcp --help   # should sit on stdio waiting for MCP traffic; Ctrl+C to exit

If the command isn't found, you likely installed into a Python install whose Scripts/ (Windows) or bin/ (macOS/Linux) directory isn't on PATH. Either fix PATH, install via pipx install arythmatic-connect-mcp, or use the absolute path in your agent config (see Troubleshooting).

Get a tenant API key

The MCP server authenticates as the tenant API key owner — every action the agent takes is performed as if that user did it (matching their permission scopes in the community UI).

1. Sign in to your community as a workspace admin.
2. Go to https://<your-tenant>.connect.arythmatic.cloud/w/<slug>/admin/api-keys.
3. Create a key — copy the arc_live_<prefix>_<secret> value immediately (only shown once).

Required environment variables

The MCP server reads two env vars at startup:

Var	Value
ARYTHMATIC_API_BASE_URL	https://api.connect.arythmatic.cloud/api/v1 (the /api/v1 suffix is REQUIRED)
ARYTHMATIC_API_KEY	The arc_live_... key from above

For a self-hosted / dev environment, swap the host accordingly (e.g. https://api.connect-dev.arythmatic.cloud/api/v1).

---

Wire into your agent

Each MCP host has a different config file shape — pick yours.

Claude Desktop

⚠️ Note: as of mid-2026 Anthropic has been migrating users from the Desktop app toward Claude Code (the CLI). The Desktop app still works but if you find it slow, Claude Code below is a lighter alternative.

Edit claude_desktop_config.json:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "arythmatic-connect": {
      "command": "arythmatic-connect-mcp",
      "env": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}

Restart Claude Desktop. The Connect tools appear in the tools picker (look for the hammer icon in the chat input).

Claude Code (terminal)

Claude Code is Anthropic's official CLI — works on Windows / macOS / Linux. Register the MCP server with one command:

claude mcp add arythmatic-connect arythmatic-connect-mcp \
  -e ARYTHMATIC_API_BASE_URL=https://api.connect.arythmatic.cloud/api/v1 \
  -e ARYTHMATIC_API_KEY=arc_live_xxxxxxxx_yyyyyyyyyyyy

Useful flags:

• -s user — register globally (available in every project).
• -s project — write a .mcp.json committed alongside the repo so teammates pick it up too.
• Default scope is local (this project / directory only).

Then verify:

claude mcp list                       # confirms the server is wired and connects
claude mcp get arythmatic-connect     # shows the stored command + env

Start a claude session and try "list my workspaces" — it should invoke list_workspaces via MCP.

Windows tip: if claude mcp list says "Failed to connect" because the shim isn't on PATH, re-register using the absolute path:

claude mcp add arythmatic-connect "C:\Users\<you>\AppData\Local\Programs\Python\Python313\Scripts\arythmatic-connect-mcp.exe" -e ARYTHMATIC_API_BASE_URL=... -e ARYTHMATIC_API_KEY=...

Cursor

Cursor uses the same mcpServers schema as Claude Desktop. Create ~/.cursor/mcp.json for global access or .cursor/mcp.json in a specific project:

{
  "mcpServers": {
    "arythmatic-connect": {
      "command": "arythmatic-connect-mcp",
      "env": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}

Then enable the server in Settings → MCP.

opencode (terminal)

opencode is an open-source AI coding agent for the terminal. Edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arythmatic-connect": {
      "type": "local",
      "command": ["arythmatic-connect-mcp"],
      "environment": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}

Restart opencode — tools appear in the agent's tool list. opencode's MCP schema occasionally evolves; if the keys above no longer match, see https://opencode.ai/docs/mcp.

VS Code — GitHub Copilot

GitHub Copilot supports MCP in Visual Studio Code (Copilot Chat / Agent Mode). Workspace config goes in .vscode/mcp.json:

{
  "servers": {
    "arythmatic-connect": {
      "type": "stdio",
      "command": "arythmatic-connect-mcp",
      "env": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}

For global config, add the same servers block to Settings → MCP: Server Definitions (user-level settings). Restart VS Code. Enable Agent Mode in Copilot Chat to see the tools.

VS Code — Continue

Continue reads ~/.continue/config.yaml:

mcpServers:
  - name: arythmatic-connect
    command: arythmatic-connect-mcp
    env:
      ARYTHMATIC_API_BASE_URL: https://api.connect.arythmatic.cloud/api/v1
      ARYTHMATIC_API_KEY: arc_live_xxxxxxxx_yyyyyyyyyyyy

Restart the Continue extension. Tools appear in the agent's tool registry.

OpenAI Codex (CLI)

OpenAI Codex CLI uses TOML config at ~/.codex/config.toml:

[mcp_servers.arythmatic-connect]
command = "arythmatic-connect-mcp"
args = []

[mcp_servers.arythmatic-connect.env]
ARYTHMATIC_API_BASE_URL = "https://api.connect.arythmatic.cloud/api/v1"
ARYTHMATIC_API_KEY = "arc_live_xxxxxxxx_yyyyyyyyyyyy"

Restart codex. The Connect tools are available to the agent.

Anything else

Any MCP-spec-compliant host can spawn the server. The contract is:

• Transport: stdio
• Command: arythmatic-connect-mcp (or absolute path to the shim, or python -m arythmatic_connect_mcp from inside a venv where the package is installed)
• Env: ARYTHMATIC_API_BASE_URL + ARYTHMATIC_API_KEY

If your host has a different config schema, follow its docs — the command + env are the only universal pieces.

---

Available tools (v0.2)

47 tools across 9 categories. Every call is a thin pass-through to the Arythmatic Connect REST API authenticated as the API-key owner; the backend enforces permission scopes.

Discovery

Tool	Description
get_current_user	Who the agent is acting as + their permission scopes.
list_workspaces	Workspaces the caller is a member of.
list_channels	Channels inside a workspace.
search_content	Cross-tenant search across posts, articles, questions, channel messages.

Channel chat

Tool	Description
list_channel_messages	Recent messages in a channel (paginated).
post_channel_message	Send a message to a channel.
edit_channel_message	Edit your own channel message.
react_to_channel_message	Toggle an emoji reaction on a channel message.

Feed posts

Tool	Description
list_feed_posts	Recent feed posts in a workspace.
create_feed_post	Create a text feed post (no images in v0.2).
edit_post	Edit your own feed post.
react_to_post / remove_reaction_from_post	Upsert / clear a named reaction (like, love, …).
comment_on_post	Top-level comment on a feed post.

Direct messages

Tool	Description
list_conversations	DM and group chat conversations the caller is part of.
list_conversation_messages	Messages in a single conversation.
send_conversation_message	Reply in a DM or group chat.
edit_conversation_message	Edit your own message.
react_to_conversation_message	Toggle an emoji reaction on a DM / group message.

Long-form content

Tool	Description
create_article	Publish a Markdown article in a workspace.
edit_article	Edit your own article.
react_to_article / remove_reaction_from_article	Upsert / clear a named reaction.
comment_on_article	Top-level comment on an article.
create_question	Open a new Q&A question.
edit_question	Edit your own question.
comment_on_question	Top-level comment on a question.

Polls

Tool	Description
create_poll	Create a poll with 2–20 options.
get_poll	Read poll detail (needed to find option UUIDs before voting).
vote_on_poll	Cast a vote (requires option UUID, not index).
close_poll	Stop the poll from accepting further votes.

Quizzes — multi-step draft flow

Quizzes are composed piecewise so the agent can preview the full quiz with the user before publishing. Drafts live only in MCP-server memory for the duration of the session — they aren't persisted on the backend until publish_quiz_draft is called.

Tool	Description
create_quiz_draft	Start an in-memory draft. Returns a local draft_id.
add_quiz_question	Append a question (MCQ / true-false / multi-select / short-answer).
list_quiz_draft_questions	Show the full draft (for user review before publishing).
discard_quiz_draft	Throw away an in-progress draft.
publish_quiz_draft	Commit the draft to the backend in one atomic POST.

Recommended flow: agent constructs the questions, calls list_quiz_draft_questions, shows the user, gets explicit confirmation, then publish_quiz_draft. This protects the leaderboard from a buggy "correct answer" pick by the agent.

Notifications

Tool	Description
list_notifications	Caller's inbox (filter unread_only=true for what's new).
mark_notifications_read	Mark specific notifications by UUID.
mark_all_notifications_read	One-shot "clear my inbox".

Support tickets

Tool	Description
list_my_tickets	Tickets the caller has filed.
create_ticket	File a new support ticket (workspace-scoped or tenant-wide).
get_ticket	Read a ticket's body + status.
list_ticket_comments	List ticket comments.
comment_on_ticket	Reply on a ticket (with optional is_internal for staff handoff).

Admin / moderator

Require the caller's API key to be minted by an admin/moderator. The relevant scope is enforced server-side, same as the web UI.

Tool	Description
list_all_tickets	Tenant-wide ticket queue. Requires tickets:manage.
update_ticket	Change a ticket's status / assignee. Requires tickets:manage.
list_workspace_members	Members of a workspace. Requires members:view.

---

Security model

• Authentication: the tenant API key acts as the caller. There's no per-tool gating in the MCP server itself — the Django API enforces scopes on every request, returning 403 when the calling key lacks the right scope. If your agent shouldn't be able to do something, mint a key with narrower scopes via the admin API-keys UI.
• Audit: every API call lands in integrations.APIKeyUsageLog (90-day retention) just like any other key-driven call, so you can audit the agent's behaviour after the fact.
• Quiz answers: list_quiz_draft_questions returns the is_correct flag on each option. Share that output only with the quiz author for review — never paste it back to people who will take the quiz.

Troubleshooting

"Failed to connect" in agent host The MCP host can't spawn the server. Usually one of:

1. Package not installed — pip install arythmatic-connect-mcp or check pip show arythmatic-connect-mcp.
2. Console shim not on PATH — use the absolute path to arythmatic-connect-mcp.exe (Windows) / arythmatic-connect-mcp (macOS / Linux), or install via pipx.
3. Wrong Python env — if you've got multiple Python installs, the shim may live in one that isn't first on PATH. which arythmatic-connect-mcp (macOS / Linux) / where arythmatic-connect-mcp (Windows) tells you which one wins.

Every call returns 404 ARYTHMATIC_API_BASE_URL is missing the /api/v1 suffix. The full value must be https://api.connect.arythmatic.cloud/api/v1, not …/.

Every call returns 401 / 403

• 401: API key is wrong, revoked, or expired. Mint a fresh one in the admin UI.
• 403: the key's owner lacks the scope the tool needs. E.g. list_all_tickets requires tickets:manage. Either grant the user the right role or use a key minted by someone with the scope.

Tools don't show up after editing config Most hosts spawn the MCP server lazily on each session. Fully quit + restart the host (close the terminal / app) — reloading a project window often isn't enough.

Publishing

cd mcp/
pip install build twine
python -m build
python -m twine upload dist/*

Bump version in pyproject.toml, src/arythmatic_connect_mcp/__init__.py, and the User-Agent in src/arythmatic_connect_mcp/client.py before building. Tag the release on GitHub matching the version.

Local development

cd mcp/
pip install -e ".[dev]"
pytest

Run the server manually to sanity-check tool registration:

ARYTHMATIC_API_BASE_URL=http://localhost:8000/api/v1 \
ARYTHMATIC_API_KEY=arc_test_xxxx \
python -m arythmatic_connect_mcp

(Stdio-mode — you can pipe MCP JSON-RPC at it manually if you want, but typically you wire it into an MCP client.)