> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent-mintlify-f21cea86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. This is the same [Model Context Protocol](https://modelcontextprotocol.io) 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](/guides/ai-agents). IDE workflow: [How to code with Arka](/guides/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

```bash theme={null}
# 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:

```fish theme={null}
arka mcp list
arka mcp status
arka mcp tools signoz
```

Natural language (agent routing):

```fish theme={null}
arka "list mcp servers"
arka "mcp status"
arka "list mcp tools from signoz"
```

## Config format

`~/.config/arka/mcp.json`:

```json theme={null}
{
  "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

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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`](https://github.com/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:

```bash theme={null}
arka mcp preset threejs
```

Apply it to Arka's MCP config:

```bash theme={null}
arka mcp preset threejs --apply
arka mcp tools threejs
```

The preset uses Docker:

```json theme={null}
{
  "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 |

<Note>
  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.
</Note>

## 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.

<Steps>
  <Step title="Install Arka">
    From the repo (editable install) or your venv:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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`:

    ```bash theme={null}
    arka mcp install
    ```

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

    ```json theme={null}
    {
      "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) |
  </Step>

  <Step title="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.
  </Step>

  <Step title="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):

    ```bash theme={null}
    arka mcp call arka arka_recall --args '{"goal":"theme"}'
    arka mcp call arka arka_ask --args '{"prompt":"what is arka?"}'
    ```
  </Step>
</Steps>

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "command": "/absolute/path/to/arka",
  "args": ["mcp", "serve"]
}
```

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

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```bash theme={null}
ARKA_MCP_ENABLE_PERSONAL_SKILLS=1 arka mcp serve
```

For a narrower override:

```bash theme={null}
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:

```bash theme={null}
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](/guides/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:

```bash theme={null}
# 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](/guides/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

```bash theme={null}
# 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:

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.


## Related topics

- [How Arka compares to other agents](/concepts/comparison.md)
- [Generate music](/guides/generate-music.md)
- [Agent Hub](/guides/agent-hub.md)
- [AI agent guide — use Arka over MCP](/guides/ai-agents.md)
- [Arka — AI terminal agent documentation](/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.