karma-connect

One command that wires the Karma MCP server into every agent host on this machine.

pip install ./packages/karma-connect
# or, without cloning the repo:
pip install "karma-connect @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-connect"
karma-connect detect
karma-connect install

Not on PyPI yet (pip install karma-connect returns 404); see docs/mcp/karma-mcp-integration.md.

No JSON editing, no config file archaeology. It finds the hosts you already have and writes one named server entry into each.

Which server it wires

karma-mcp-server (packages/karma-mcp-server) - the thin access layer that only ever holds KARMA_RUNTIME_KEY. The older karma-mcp package is not used: it wanted KARMA_PRIVATE_KEY injected into the MCP process, which the security audit retired, and karma-mcp-server refuses to start when private key material is in its environment. So install refuses --env KARMA_PRIVATE_KEY=... (or any mnemonic key) instead of writing a server that can never boot.

KARMA_RUNTIME_URL defaults to the public node (https://karma-network.ai), so a fresh install needs no --env at all. Everything else the agent needs arrives when the owner approves the pairing.

What it touches

Only that one entry is touched; every other line is preserved. Running install twice changes nothing the second time.

Gotchas it handles for you

• Muse Code wants "type": "stdio" (its docs page says transport, the binary does not) plus schema_version: 1, and it drops the whole MCP block if mcp_servers and mcpServers ever appear together. This tool only writes mcpServers.
• Codex keeps MCP servers in TOML tables, not JSON, so the writer replaces just the [mcp_servers.karma] block and leaves your model, plugins and marketplaces alone.
• OpenClaw nests under mcp.servers, not mcpServers.

Commands

• karma-connect detect - which hosts exist here, and where their config lives
• karma-connect install [--host codex,muse] [--dry-run] - write the entry
• karma-connect doctor - is karma-mcp-server reachable, is every config readable, is this machine paired yet
• karma-connect sign-check - print the per-request signature this machine would send

After installing

1. Restart the agent host so it reloads MCP servers.
2. Have the agent call karma_connect (agent_name = whatever it calls itself). It prints a user_code and a verification_uri - open that link in Karma Console, check the agent_fingerprint on the card matches the one the agent showed you, set the limits, and approve.
3. Have the agent call karma_connect_claim. Approval is activation, so the credentials come back directly - there is no 8-character code to relay.
4. Credentials land in ~/.karma/agent.env (0600). Nothing secret travels through chat.

The 8-character handoff code still exists as a fallback for machines that cannot generate a local agent key, and the console can add an email-receipt gate as a third lock when the approval carries notify_email.