MCP integration for Cursor and Claude

Connect Arka to Model Context Protocol servers — stdio or HTTP — expose 70+ Arka skills to Cursor and Claude Desktop, list tools, call tools, and verify health from the CLI.

Arka can connect to any MCP server from the terminal — the same Model Context Protocol used by Cursor, Claude Desktop, and other AI clients.

Summary: Arka is both an MCP client (call external servers like SigNoz or filesystem) and an MCP server (expose Arka skills to Cursor). Config lives at ~/.config/arka/mcp.json in Cursor-compatible format. Quick start: arka mcp list, arka mcp add, arka mcp tools, arka mcp call. See also How to code with Arka for IDE workflow.

MCP servers can also participate in Arka’s universal plugin catalog. After adding a server, use arka plugin doctor and arka plugin inspect <name> to check its normalized capabilities and permissions before routing requests to it. Agent Hub exports the same catalog alongside Arka’s skill manifest.

Config lives at ~/.config/arka/mcp.json in Cursor-compatible mcpServers format.

Quick start

# List configured servers
arka mcp list

# Add a stdio MCP server (command + args)
arka mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp

# Add an HTTP/SSE MCP server
arka mcp add signoz --url http://localhost:8000/mcp \
  --header SIGNOZ-API-KEY=$SIGNOZ_API_KEY

# List tools from a server
arka mcp tools signoz

# Call a tool
arka mcp call signoz signoz_ask --args '{"question":"error rate last hour"}'

# Check connection health
arka mcp status

From fish:

arka mcp list
arka mcp status
arka mcp tools signoz

Natural language (agent routing):

agent "list mcp servers"
agent "mcp status"
agent "list mcp tools from signoz"

Config format

~/.config/arka/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "signoz": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "SIGNOZ-API-KEY": "<your-api-key>"
      }
    }
  }
}

Stdio servers use command + args. Remote servers use url + optional headers. Optional env values support ${env:VAR_NAME} substitution.

Transports

Transport	Config	Example
stdio	command + args	npx -y @modelcontextprotocol/server-filesystem /tmp
HTTP/SSE	url + headers	SigNoz MCP at http://localhost:8000/mcp

Arka reuses the existing HTTP MCP client for remote servers and a built-in newline-delimited JSON-RPC client for stdio — no extra dependencies required.

Optional Python SDK

pip install mcp

Arka works without the SDK. If it is installed, Arka detects it (arka mcp status shows sdk on).

SigNoz MCP

For SigNoz specifically, Arka also ships traced helpers (arka signoz status, goal self-heal). Generic arka mcp works with any MCP server — not only SigNoz.

arka mcp add signoz --url http://localhost:8000/mcp --header SIGNOZ-API-KEY=$SIGNOZ_API_KEY
arka mcp tools signoz

MCP logs

Use MCP logs when Cursor, Claude, or another MCP client reports production-like issues such as Connection closed, invalid tool arguments, unknown tools, or server error states:

arka mcp logs
arka mcp logs -n 100 --json
arka mcp logs --event server.tools_call

Logs are JSONL and store sanitized client/server events: timestamp, component, method/tool, status, duration, and a short error snippet. Secrets, tokens, and authorization-like fields are redacted. By default the file lives under Arka’s config directory at logs/mcp.jsonl; set ARKA_MCP_LOG_PATH to override it for tests or hosted deployments.

Three.js model MCP

Arka has a built-in preset for baryhuang/mcp-threejs, a Sketchfab-backed MCP server for finding downloadable Three.js-compatible 3D assets. This is useful when a scene asks for real things such as satellites, spacecraft, vehicles, rooms, desks, or humans — Arka should prefer a licensed GLTF/GLB asset over rough geometric placeholders.

Preview the config first:

arka mcp preset threejs

Apply it to Arka’s MCP config:

arka mcp preset threejs --apply
arka mcp tools threejs

The preset uses Docker:

{
  "mcpServers": {
    "threejs": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "buryhuang/mcp-server-threejs:latest"],
      "env": {
        "SKETCHFAB_ACCESS_TOKEN": "${env:SKETCHFAB_ACCESS_TOKEN}",
        "SKETCHFAB_REFRESH_TOKEN": "${env:SKETCHFAB_REFRESH_TOKEN}",
        "SKETCHFAB_CLIENT_ID": "${env:SKETCHFAB_CLIENT_ID}",
        "SKETCHFAB_CLIENT_SECRET": "${env:SKETCHFAB_CLIENT_SECRET}"
      }
    }
  }
}

Set the Sketchfab OAuth variables when you want live download-link lookup. Without tokens, the server may start but model lookup/download URLs can fail depending on the upstream API.

Commands reference

Command	Description
arka mcp list	List configured MCP servers
arka mcp add <name> <command> [args...]	Add stdio server
arka mcp add <name> --url <url>	Add HTTP/SSE server
arka mcp add <name> --url <url> --header KEY=VAL	Add HTTP server with auth header
arka mcp preset threejs [--apply]	Preview/apply the Three.js model MCP server preset
arka mcp remove <name>	Remove a server
arka mcp tools <server>	List tools from a server
arka mcp call <server> <tool> [--args '{}']	Call a tool
arka mcp status	Connection health for all servers
arka mcp logs [-n 50] [--json]	Show recent sanitized MCP client/server events
arka mcp self-tools	List Arka’s native MCP tools
arka mcp serve	Start Arka as a local stdio MCP server
arka mcp install	Print Cursor/Claude-compatible mcp.json snippet
arka mcp doctor	Verify the local Arka MCP server starts

MCP tool calls open a fresh connection per invocation. For high-frequency use, prefer keeping servers local (stdio) or on a low-latency HTTP endpoint.

Arka as MCP server

Other agents (Cursor, Claude Desktop, OpenClaw, Codex, etc.) can call Arka skills and memory over MCP — the same stdio transport Arka uses as an MCP client.

Cursor setup

Use Arka as an MCP server inside Cursor so the editor agent can call arka_ask, arka_recall, arka_skill, and the rest of Arka’s exported tool surface.

1. Install Arka

   From the repo (editable install) or your venv:

   cd /path/to/arka
   python -m venv venv-arka
   source venv-arka/bin/activate
   pip install -e .
   arka mcp doctor
   

   arka mcp doctor should end with summary ok and report the current tool count.

2. Add MCP config

   Option A — project-level (recommended when working in the Arka repo): copy or symlink .cursor/mcp.json from the repo root. Cursor loads it automatically for this workspace.

   Option B — global: open Cursor Settings → MCP and merge the arka entry into ~/.cursor/mcp.json:

   arka mcp install
   

   Example snippet (paths vary by machine — use arka mcp install for yours):

   {
     "mcpServers": {
       "arka": {
         "command": "/Users/you/dev/arka/venv-arka/bin/arka",
         "args": ["mcp", "serve"],
         "env": {
           "ARKA_CONFIG_DIR": "/Users/you/.config/arka"
         }
       }
     }
   }
   

   Repo helpers:

   File	Purpose
   .cursor/mcp.json	Project-level Cursor MCP (Arka only)
   hub/adapters/cursor_mcp_snippet.json	Copy-paste snippet + install steps
   mcp.json	Hub-ready config (Arka + optional context7)

3. Restart Cursor

   Fully quit and reopen Cursor, or use Settings → MCP → Reload. The arka server should show as connected with the current Arka tool count.

4. Example tool calls

   In Cursor chat, ask the agent to use Arka MCP tools:

   • Recall memory: call arka_recall with {"goal": "project conventions"}
   • Ask Arka: call arka_ask with {"prompt": "summarize this repo"}
   • Run a skill: call arka_skill with {"skill": "repo_map"}
   • Repo layout: call arka_repo_map with {"depth": 2}

   From the terminal (same tools, no Cursor):

   arka mcp call arka arka_recall --args '{"goal":"theme"}'
   arka mcp call arka arka_ask --args '{"prompt":"what is arka?"}'
   

IDE and agent setup

Arka exposes a standard stdio MCP server, so the same generated entry works in most MCP-compatible IDEs. Generate a machine-specific snippet instead of copying a path from this page:

arka mcp install

Add the printed mcpServers.arka entry to the client’s MCP JSON file, then restart or reload its MCP panel. The entry is:

{
  "command": "/absolute/path/to/arka",
  "args": ["mcp", "serve"]
}

If the IDE cannot resolve your virtual environment, use an absolute Python executable and module invocation:

{
  "command": "/absolute/path/to/venv/bin/python",
  "args": ["-m", "arka", "mcp", "serve"]
}

Client	Configuration location / action
Cursor	Settings → MCP, or project .cursor/mcp.json
VS Code / GitHub Copilot	.vscode/mcp.json in the workspace, or the MCP server settings UI
Claude Desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Linux: ~/.config/Claude/claude_desktop_config.json
Windsurf	MCP settings → add server, or ~/.codeium/windsurf/mcp_config.json
Cline	Cline MCP Servers panel → install from JSON
Continue	Add the server in Continue’s MCP configuration (use the generated stdio entry)
Zed	Settings → Context Servers → add an arka command server
Codex CLI	~/.codex/config.toml MCP configuration, or run codex mcp add arka -- arka mcp serve

After configuring any client, verify the connection before asking the agent to use Arka:

arka mcp doctor
arka mcp self-tools

In the IDE, explicitly say “use the Arka MCP tools” when needed. Treat arka_route as the umbrella Arka MCP tool: pass the user’s full natural-language request to it when you are not certain which narrower Arka tool should run. Useful first checks are arka_heartbeat, arka_repo_map, and arka_skill. Existing MCP servers are preserved when using arka agent_hub sync --unify; use arka agent_hub adapters to preview which client files will be updated.

Quick start

# Start the server (stdio — used by MCP clients automatically)
arka mcp serve

# Print config for Cursor or Claude Desktop
arka mcp install

# Add arka to ~/.config/arka/mcp.json and print snippet
arka mcp install --write-config

# Verify initialize + tools/list
arka mcp doctor

Editable installs without arka on PATH:

{
  "mcpServers": {
    "arka": {
      "command": "python",
      "args": ["-m", "arka", "mcp", "serve"]
    }
  }
}

Run arka mcp install to print the correct command for your machine.

Exposed tools

Tool	Description
arka_ask	Ask Arka (web, memory, calc, weather, chat)
arka_remember	Store a fact, note, or channel turn
arka_recall	Recall unified memory by goal
arka_skill	Invoke a named Arka skill
arka_route	Umbrella tool — route and execute the full natural-language request through Arka skills/MCP-backed capabilities
arka_repo_map	Repository layout and Python symbols
arka_heartbeat	Agent heartbeat — ping, status, or recent activity history
arka_sessions	Channel sessions — list, status, context, resume, silence_check, push, reset
arka_routines	Scheduled routines — list, add, remove, enable, or disable
arka_session_memory	OpenClaw markdown memory — append, search, context, status, clear
arka_subagent	Hermes sub-agent delegation — spawn, list, status, resume
arka_project_rules	Cursor-style project rules — AGENTS.md, CLAUDE.md, .cursor/rules
arka_webhook	Webhook gateway — status or health
arka_view_data	Preview CSV/TSV tables as plain text
arka_clipboard	Clipboard history — list, save, get, or clear
arka_share	Share last LLM response with model, provider, tokens, latency, and output (markdown or JSON)
arka_remind	Reminders — list, add, or cancel
arka_bookmarks	Bookmarks — list, save, search, get, or delete
arka_docker	Docker — health, containers, images, or logs
arka_jsonkit	JSON — validate, pretty, minify, or get by path
arka_timekit	Time — now, timezone convert, or relative offsets
arka_urlkit	URL helpers — parse, normalize, or slugify
arka_password	Password — generate one-shot secret (not stored)
arka_spotify	Spotify — search tracks; hidden by default in MCP personal-skill safe mode
arka_textkit	Textkit — UUID, hash, or base64 encode/decode
arka_calendar	Calendar — today’s events (macOS Calendar.app)
arka_platform	Platform — show or detect OS capabilities
arka_personalize	Personalize — profile status, skill tips, quickstart
arka_persona	Personas — list or show persona configs
arka_github	GitHub — resolve repo or fetch recent activity
arka_price	Price check — list retailer sources or parse a query
arka_config	Config — list files/dirs or show paths (read-only)
arka_sports	Sports — live scores or list leagues
arka_qr	QR code — encode text/URL as ASCII art
arka_currency	Currency — convert amounts or parse NL queries
arka_disk	Disk space — usage summary or category breakdown
arka_repo_health	Repo health — scan or run lint/test checks
arka_agent_hub	Agent Hub — status, adapters, detect, doctor, list, memory sources, or import IDE memory
arka_team_run	Run an agent team workflow

MCP-safe defaults

Arka MCP hides or blocks personal desktop/device skills by default so IDE agents do not unexpectedly open Brave, start Spotify, play media, or run a personalized daily brief. This does not change local Fish/CLI behavior.

Disabled-by-default MCP examples:

• arka_spotify
• play_spotify, spotify_control, spotify_brave_debug
• play_song, play_youtube, play_movie, stop_music
• open_url, open, browse, open_urls
• search_web, browse_web, agent_browser
• daily_brief

Headless/dev-safe tools such as browser_check, web_screenshot, automate, repo tools, code tools, data tools, and arka_route remain available.

Opt in only when the MCP client is trusted to touch your desktop/browser/media state:

ARKA_MCP_ENABLE_PERSONAL_SKILLS=1 arka mcp serve

For a narrower override:

ARKA_MCP_ENABLED_TOOLS=arka_spotify arka mcp serve
ARKA_MCP_ENABLED_SKILLS=daily_brief,open_url arka mcp serve

Agent Hub

agent_hub sync copies MCP config to the hub and ensures the arka self-server entry is present so other launch agents can merge it:

arka agent_hub sync
arka agent_hub adapters    # see which agent configs would gain hub servers

Hub env vars (ARKA_MCP_CONFIG, ARKA_HUB_DIR) are documented in Agent Hub.

Import IDE memory via MCP

arka_agent_hub can list and import memory from Cursor, Codex, OpenClaw, Arka session notes, and hub exports:

# List importable memory files on this machine
arka mcp call arka arka_agent_hub --args '{"action":"memory_sources"}'

# Import one IDE source or everything detected
arka mcp call arka arka_agent_hub --args '{"action":"import_memory","source":"cursor"}'
arka mcp call arka arka_agent_hub --args '{"action":"import_memory","all":true}'

# Import an explicit export file
arka mcp call arka arka_agent_hub --args '{"action":"import_memory","path":"~/.config/arka/hub/memory/summary.json"}'

action	Parameters	Returns
memory_sources	—	Array of { id, name, ide, files, file_count } for sources that exist locally
import_memory	path or source / ide / agent or all: true	{ ok, facts_imported, notes_imported, imports, errors }

Other arka_agent_hub actions: status, adapters, detect, doctor, list. See Agent Hub — Memory import for source ids and formats.

Using Arka MCP to extend Arka

Dogfood the MCP workflow when adding skills: use Arka’s own MCP tools to discover gaps, then wire new capabilities back into CLI routing.

Example workflow

# Verify the local MCP server
arka mcp doctor

# Inspect repo layout and health (same tools Cursor agents call)
arka mcp call arka arka_repo_map --args '{"depth":2,"path":"/path/to/arka"}'
arka mcp call arka arka_repo_health --args '{"path":"/path/to/arka"}'

# List Arka's native MCP surface
arka mcp self-tools

# From fish / NL
agent "list arka mcp tools"
agent "show agent heartbeat"
agent "validate json package.json"

When a tool exists on the MCP server but lacks natural-language routing (for example arka_heartbeat or arka_jsonkit), add:

1. route_command() in the Python module
2. route_*() in src/arka/routing/symbolic.py
3. Fish helpers _agent_is_*_request / _agent_route_* in config.fish
4. Tests in tests/test_*_routing.py and tests/test_nl_routing_coverage.py

This keeps Cursor MCP, terminal NL, and ROUTE_MODE=symbolic_only in sync.

Browser safety

MCP requests do not open websites or desktop browser windows implicitly. Use headless skills such as browser_check, web_screenshot, or automate for inspection. If a workflow genuinely needs a headed tab, call the arka_skill tool with allow_browser: true after obtaining user approval. This prevents a model-generated URL from unexpectedly launching a browser.