> ## Documentation Index > Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0). > Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration. > Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka. # 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](https://modelcontextprotocol.io) 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](/guides/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 ` 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} agent "list mcp servers" agent "mcp status" agent "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": "" } } } } ``` 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 ```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. 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`](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 [args...]` | Add stdio server | | `arka mcp add --url ` | Add HTTP/SSE server | | `arka mcp add --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 ` | Remove a server | | `arka mcp tools ` | List tools from a server | | `arka mcp call [--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. 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. **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) | Fully quit and reopen Cursor, or use **Settings → MCP → Reload**. The `arka` server should show as connected with the current Arka tool count. 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?"}' ``` ## 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`. 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 ```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_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 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. ## Related topics - [Arka — AI terminal agent documentation](/index.md) - [How to code with Arka](/guides/code-with-arka.md) - [Agent Hub](/guides/agent-hub.md) - [Automatic MCP configuration](/guides/mcp-auto.md) - [Life sciences (Anthropic marketplace)](/guides/life-sciences.md)