MCP Quickstart

Pro Labs

Install @arkanis/mcp-server, pair this machine with a guild, wire your MCP client of choice, and watch the first audited tool call land in your dashboard. Claude Desktop and Claude Code are the worked examples; the same server connects to any MCP-compatible client.

What is this?

A five-step setup: install the @arkanis/mcp-serverCLI, run the pair flow, approve in the dashboard, paste a one-line config into your MCP client, ask your first question. The walkthrough uses Claude Desktop and Claude Code; the same server connects to Cursor, Zed, Continue, Cline, Windsurf, Cody, Goose, and any other MCP-compatible client.

Why you might want it

Ask your assistant questions about your guild in plain English: "what strikes does this user have", "list open tickets", "run this RCON command". Every tool call is audit-logged withactor_source=mcpso the source of every action is reconstructable.

Setup time: about 3 minutesDifficulty: Easy. Most users get through it first try.

Happy path

What this is for

Pointing Claude Desktop, Claude Code, or any MCP-compatible client at one of your Arkanis guilds so the assistant can list strikes, claim tickets, run RCON, and other tools, with every call audit-logged as actor_source=mcp.

Before you start

·Your guild is on the Pro tier. (MCP is currently Pro Labs early access.)
·You are the Discord guild owner (only the owner can approve a pair request in v1).
·Node 20+ on the machine that will host the MCP server.
·An MCP-compatible client installed locally (Claude Desktop and Claude Code are actively tested).

5-minute setup

1Install the CLI: npm install -g @arkanis/mcp-server (or use npx).
2Run arkanis-mcp pair --guild <your-guild-id>. The CLI prints an 8-character user code and the dashboard URL.
3Open the URL or go to Settings → API & MCP → MCP Tokens, paste the code, click Authorize.
4The CLI exits with success and writes a token to the per-user config. Restart your MCP client (Claude Desktop or Claude Code) so it picks up the new config file.
5In your assistant, ask a read question like “what strikes does user X have”. A successful tool call confirms the wire is live; the audit row shows up under the MCP filter in the dashboard.

Common failure modes

USER_CODE_EXPIRED when approving
The 10-minute TTL on the pair code elapsed, or the dashboard saw repeated failed approval attempts. Run arkanis-mcp pair again to mint a fresh code, then approve as the guild owner.
Tools do not appear in Claude after pairing
Claude reads its config only at start-up. Fully quit Claude Desktop (or restart Claude Code) and reopen. Confirm the JSON in the config path table is valid and points at arkanis-mcp on your PATH.
CLI hangs at "waiting for approval" forever
Your machine cannot reach https://api.arkanis.gg. Corporate firewall or VPN. Confirm the URL resolves and returns 200 from the same shell where arkanis-mcp pair runs.

Per-client config paths, the destructive-action flow, the audit-row shape, and the troubleshooting matrix are documented below.

Status

The MCP server is in Pro Labs early access. It is opt-in per guild, gated behind the same Pro entitlement as the REST API, and shares the same token primitives. The REST API is GA. The MCP server is feature-complete for v1 but the surface and CLI ergonomics may shift before it leaves Labs.

⭐

Pro

Free guilds can read this page, but pairing and tool calls require a Pro guild. The dashboard surface that mints tokens (API & MCP) is gated behind a per-browser Developer Mode toggle on the Settings Panel — flip it on once as the guild owner to expose the entry in your sidebar.

Requirements

Node 20 or newer on the machine that will host the MCP server.
An Arkanis Pro guild. The MCP token mint surface lives at Settings Panel → Developer Mode (one-time toggle) → API & MCP in the sidebar.
A Discord account with the capabilities you want to expose. The token snapshot inherits exactly what you have at pair time.
An MCP-compatible client installed locally. See Which clients work? below for the list. Claude Desktop and Claude Code are the two we actively test against.

The CLI is published to npm as @arkanis/mcp-server. The bin name after install is arkanis-mcp. The companion CLI doc lives in the package README and targets command-line users; this page targets dashboard users coming from the web.

Which Clients Work?

Any MCP-compatible client works. The Arkanis MCP server speaks the open Model Context Protocol over stdio. You are not locked into Claude.

The clients below are known to be MCP-compatible at the time of writing. The two marked verified are the ones we actively test against on each release. The others speak the same protocol and the same server runs against them, but specific config syntax differs per client — check each client's own MCP docs for the exact paste-target.

Client	Status	MCP docs
Claude Desktop	Verified	MCP client list
Claude Code	Verified	Claude Code MCP guide
Cursor	MCP-compatible	Cursor MCP guide
Zed	MCP-compatible	Zed MCP guide
Continue	MCP-compatible	Continue MCP guide
Cline	MCP-compatible	Cline MCP guide
Windsurf	MCP-compatible	Windsurf MCP guide
Sourcegraph Cody	MCP-compatible	Cody agentic docs
Goose	MCP-compatible	Goose extensions

ℹ️

Note

The MCP ecosystem moves fast. If your client isn't listed but you know it speaks MCP over stdio, it will work. If something breaks against a non-verified client, file a report at support@arkanis.gg and we'll triage. The verified set is where we guarantee a working config on every release.

Walkthrough

The flow is five short steps. Plan for about three minutes the first time.

Install the CLI

Install once, globally. You can also run it through npx if you prefer not to install global packages.

npm install -g @arkanis/mcp-server

Verify the install:

arkanis-mcp --version

Pair this machine with a guild

Replace <your-guild-id> with the Discord snowflake of the guild you want to talk to. You can copy it from the dashboard URL or from Discord developer mode.

arkanis-mcp pair --guild 123456789012345678

The CLI prints three things and then waits:

A user code formatted XXXX-XXXX, for example WGNX-7K3F. Eight letters plus a separator.
The dashboard URL to open. It points at the standalone MCP pair page on the guild.
A (waiting for approval...) loop. The CLI polls every five seconds and exits when you approve or after the code expires.

ℹ️

Note

The verification code is short-lived. It expires after about ten minutes. If you take longer than that, run arkanis-mcp pair again to get a fresh code.

Approve the pair request in the dashboard

Open the URL the CLI printed. You can also navigate there directly:

Standalone approval page: /dashboard/<guildId>/mcp-pair (always reachable, no setup)
Or the MCP tab inside the API & MCP panel: /dashboard/<guildId>/settings/api-mcp. The panel only appears in your sidebar when Developer Mode is enabled (Settings Panel → Developer Mode → toggle on); the direct URL works either way.

Both surfaces accept the same code. Paste the XXXX-XXXX string into the input, click Authorize, and confirm the guild name shown matches the one you targeted from the CLI.

⚠️

Warning

Only the guild owner can approve a pair request in v1. If you are not the owner, ask the owner to run this step. Operator-tier delegation is planned for v1.1.

Once you click Authorize, the CLI exits with success and writes a token to the per-user config file. The path is ~/.config/arkanis-mcp/config.json on Linux, ~/Library/Application Support/arkanis-mcp/config.json on macOS, and %APPDATA%\arkanis-mcp\config.json on Windows. File permissions are 0600 on Unix-likes.

Configure your MCP client

The CLI prints a ready-to-paste Claude Desktop snippet at the end of the pair flow. The command and args are the same for every install; only the wrapping config shape differs per client.

{
  "mcpServers": {
    "arkanis": { "command": "arkanis-mcp", "args": ["serve"] }
  }
}

For Claude Desktop and Claude Code, paste it into the config file below. For other MCP clients, the command and args are the same — just plug them into your client's native MCP-server config format (see Which Clients Work? for links to each client's setup doc).

Client	Config path
Claude Desktop on macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop on Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop on Linux	~/.config/Claude/claude_desktop_config.json
Claude Code	Follow the Claude Code MCP guide
Other MCP clients	See Which Clients Work? for per-client setup links

Restart your MCP client after editing its config. The Arkanis tools appear in the tool list as soon as the server connects.

Ask your first question

Open a new conversation in Claude Desktop or Claude Code. Try a question that maps onto one of the read tools.

What strikes does user 234567890123456789 have on this guild?

Claude will call list_strikes under the hood. A successful response surfaces the strike rows with their severity, timestamp, and the moderator who issued each one. If the guild has no strikes for that user, Claude reports an empty result.

💡

Tip

The first call is the right moment to validate every step landed. If Claude reports a tool error, jump to Troubleshooting.

Observe the Audit Row

Every tool call is audited the same way dashboard actions are. Open the dashboard, navigate to Audit Log, and click the MCP filter chip in the source tabs. The most recent row is the call you just made.

The row shows:

actor_source = mcp — distinguishes MCP traffic from dashboard, bot, and direct REST calls.
tool_or_endpoint = list_strikes — the canonical name of the tool that ran.
actor — the Discord user that owns the token that ran the call. That is whichever account ran arkanis-mcp pair.
request_id — the same id the CLI logged on failure, useful for support requests.

ℹ️

Note

The MCP chip and per-row source pill were added in the same wave that shipped this docs page. If you do not see the chip yet, hard-refresh the dashboard.

Destructive Actions Need an Extra Step

Read tools work as soon as the pair flow completes. Reversible writes do too. Destructive actions like add_strike, ban_user, mass_purge, or rcon_run require a re-auth window. The token holder opens a 15-minute window from the dashboard, then the destructive tool can run within that window.

Claude will report RE_AUTH_REQUIRED on the first destructive call. Open /dashboard/<guildId>/settings/api-mcp, switch to the Re-auth window tab, click Approve next destructive action, then ask Claude to retry. The window stays open for 15 minutes from approval.

The full list of destructive operations and the sentinel templates each one generates lives in Destructive Actions.

Troubleshooting

"No config found" when running arkanis-mcp serve. The pair flow did not complete on this machine. Run arkanis-mcp pair --guild <guildId> first.
RE_AUTH_REQUIRED on a destructive call. Open the Re-auth window tab in Settings → API & MCP, click Approve next destructive action, retry. See Destructive Actions.
CAPABILITY_DENIED. The token snapshot does not include the capability the tool needs. Grant yourself the capability in the dashboard, then run arkanis-mcp pair again to issue a fresh token with the new snapshot.
TOKEN_REVOKED or TOKEN_EXPIRED. The token was revoked from the dashboard or it aged out. Re-run arkanis-mcp pair to issue a new one.
Tools do not appear in Claude. Confirm the MCP config file is the one Claude actually reads (see the path table above), the JSON is valid, and Claude was fully restarted after the edit.
The pair code expires before approval. Run arkanis-mcp pair again to get a fresh code. Codes live for about ten minutes.
USER_CODE_EXPIRED. The pair code died early because the dashboard saw a few failed approval attempts against it. Usually that's a typo or someone trying to approve without the right capabilities. Run arkanis-mcp pair again to mint a fresh code, then approve it as the guild owner.

Where to Next

Destructive Actions lists every destructive tool, the trigger conditions, and the confirmation sentinels the client builds.
Authentication covers token scoping, capability inheritance, expiry, rotation, and revocation. The same rules apply to MCP tokens.
Rate Limits and Errors documents the error envelope and every error code clients should handle.

Developer Overview Authentication Destructive Actions

Build in 10 Minutes Rate Limits & Errors

MCP Quickstart

What is this?

Why you might want it

What this is for

Before you start

5-minute setup

Common failure modes

Status

Requirements

Which Clients Work?

Walkthrough

Install the CLI

Pair this machine with a guild

Approve the pair request in the dashboard

Configure your MCP client

Ask your first question

Observe the Audit Row

Destructive Actions Need an Extra Step

Troubleshooting

Where to Next

Related