MCP integration for Cursor and Claude

Arka can connect to any MCP server from the terminal. This is the same Model Context Protocol used by Cursor, Claude Desktop, and other AI clients. Arka is both an MCP client (call SigNoz, filesystem, and other servers) and an MCP server (expose skills to Cursor). Config is ~/.config/arka/mcp.json. Start with arka mcp list, arka mcp add, arka mcp tools, arka mcp call. Tool routing: AI agent guide. IDE workflow: How to code with Arka. 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):

arka "list mcp servers"
arka "mcp status"
arka "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 are 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. Arka redacts secrets, tokens, and authorization-like fields. 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. This uses 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.

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.

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)

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.

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. arka agent_hub sync --unify preserves existing MCP servers; 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_music_generate`	Generate music — Pollinations elevenmusic or ffmpeg tone synthesis
`arka_meme`	Local meme templates — Drake, comparison, vibe-coding, stock photos optional
`arka_infographic`	Adaptive infographic PNG — grid/radial layout from item count
`arka_media_styles`	List meme, video, and infographic visual style presets
`arka_tech_stack`	Fuzzy-find project folder, confirm if not exact, read manifests, suggest stack
`arka_fetch_lyrics`	Fetch song lyrics, translate them, optionally generate a translated cover
`arka_safety_advice`	Curated crisis guidance — domestic violence, harassment (fixed playbook, not LLM legal advice)
`arka_local_music`	Offline music — local ffmpeg melodies (no cloud API)
`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
arka "list arka mcp tools"
arka "show agent heartbeat"
arka "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:

route_command() in the Python module
route_*() in src/arka/routing/symbolic.py
Fish helpers _agent_is_*_request / _agent_route_* in config.fish
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.

Routing & CLI

Agent & memory

Developer tools

Models & inference

Media & documents

Integrations

Finance & data

Workflows & productivity

More

MCP integration for Cursor and Claude

Quick start

Config format

Transports

Optional Python SDK

SigNoz MCP

MCP logs

Three.js model MCP

Commands reference

Arka as MCP server

Cursor setup

IDE and agent setup

Quick start

Exposed tools

MCP-safe defaults

Agent Hub

Import IDE memory via MCP

Using Arka MCP to extend Arka

Example workflow

Browser safety

​Quick start

​Config format

​Transports

​Optional Python SDK

​SigNoz MCP

​MCP logs

​Three.js model MCP

​Commands reference

​Arka as MCP server

​Cursor setup

​IDE and agent setup

​Quick start

​Exposed tools

​MCP-safe defaults

​Agent Hub

​Import IDE memory via MCP

​Using Arka MCP to extend Arka

​Example workflow

​Browser safety

Quick start

Config format

Transports

Optional Python SDK

SigNoz MCP

MCP logs

Three.js model MCP

Commands reference

Arka as MCP server

Cursor setup

IDE and agent setup

Quick start

Exposed tools

MCP-safe defaults

Agent Hub

Import IDE memory via MCP

Using Arka MCP to extend Arka

Example workflow

Browser safety