{"_id":"@altheia-xyz/mcp","_rev":"2-a992d98bd6dc0cd7d9e242a27886cfb2","name":"@altheia-xyz/mcp","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@altheia-xyz/mcp","version":"0.0.1","keywords":["mcp","model-context-protocol","solana","ai","agent","altheia"],"license":"Apache-2.0","_id":"@altheia-xyz/mcp@0.0.1","maintainers":[{"name":"altheia","email":"hello@altheia.xyz"}],"homepage":"https://altheia.xyz","bugs":{"url":"https://github.com/altheia-xyz/altheia-sdk/issues"},"bin":{"altheia-mcp":"dist/cli.js"},"dist":{"shasum":"9159a1c702407d7821485bd2312cb6b5ba83181a","tarball":"https://registry.npmjs.org/@altheia-xyz/mcp/-/mcp-0.0.1.tgz","fileCount":8,"integrity":"sha512-0MNO6a2nr7/l7R+fkA/BNFh4m9G68cC6Cn5eDmE1GqIYGK4uKQOLnO9V4v3zZy+7Ko/E4sqNR8bGdX3zKbL1fA==","signatures":[{"sig":"MEQCIGaLuZXV2K+fwZt1vuleLgMVYCqgkS/aC5R7fpIZ1PAHAiAkGQgLL+aYRSwjO4FX3UO1kECrzUkhwB/N0sWLJAKceg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":16581},"main":"./dist/index.js","type":"module","_from":"file:altheia-xyz-mcp-0.0.1.tgz","types":"./dist/index.d.ts","scripts":{"dev":"tsup src/index.ts src/cli.ts --format esm --dts --watch","test":"vitest run","build":"tsup src/index.ts src/cli.ts --format esm --dts --clean","start":"node dist/cli.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"altheia","email":"hello@altheia.xyz"},"_resolved":"/private/var/folders/z_/6656h13j1sx674klh55bc21m0000gp/T/14769542f05543d60b9423f17e9daf5a/altheia-xyz-mcp-0.0.1.tgz","_integrity":"sha512-0MNO6a2nr7/l7R+fkA/BNFh4m9G68cC6Cn5eDmE1GqIYGK4uKQOLnO9V4v3zZy+7Ko/E4sqNR8bGdX3zKbL1fA==","repository":{"url":"git+https://github.com/altheia-xyz/altheia-sdk.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.3.0","description":"Altheia MCP server — gate AI agent actions through any MCP-aware client (Claude Desktop, Cursor, ChatGPT).","directories":{},"_nodeVersion":"24.2.0","dependencies":{"zod":"^3.23.0","@altheia-xyz/sdk":"0.0.1","@altheia-xyz/types":"0.0.1","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.1_1778341034907_0.2729152103523007","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@altheia-xyz/mcp","version":"0.0.2","description":"AI agents you can fire — Altheia MCP server. Connects Claude Desktop, Cursor, ChatGPT to your gated agent fleet.","license":"Apache-2.0","homepage":"https://docs.altheia.xyz","repository":{"type":"git","url":"git+https://github.com/altheia-xyz/altheia-sdk.git","directory":"packages/mcp"},"keywords":["mcp","model-context-protocol","solana","ai","agent","altheia"],"type":"module","main":"./dist/index.js","bin":{"altheia-mcp":"dist/cli.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.0","@altheia-xyz/types":"0.0.2","@altheia-xyz/sdk":"0.0.2"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.3.0","typescript":"^5.6.0","vitest":"^2.1.0"},"types":"./dist/index.d.ts","scripts":{"build":"tsup src/index.ts src/cli.ts --format esm --dts --clean","dev":"tsup src/index.ts src/cli.ts --format esm --dts --watch","test":"vitest run","typecheck":"tsc --noEmit","start":"node dist/cli.js"},"_id":"@altheia-xyz/mcp@0.0.2","bugs":{"url":"https://github.com/altheia-xyz/altheia-sdk/issues"},"_integrity":"sha512-YGdrFbM3c0QY2kMC2fyXtVCwyH9AJlPubwEo18ZF0n/57xQEmUfFCZtk8d/Lv28mUknLxLLJVvzfuf/Mw8gZCg==","_resolved":"/private/var/folders/z_/6656h13j1sx674klh55bc21m0000gp/T/6cd741a12fb4c5fe51db65d199d39d90/altheia-xyz-mcp-0.0.2.tgz","_from":"file:altheia-xyz-mcp-0.0.2.tgz","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-YGdrFbM3c0QY2kMC2fyXtVCwyH9AJlPubwEo18ZF0n/57xQEmUfFCZtk8d/Lv28mUknLxLLJVvzfuf/Mw8gZCg==","shasum":"ace4c7f2ae9440c90b05994052fe6112dee24adb","tarball":"https://registry.npmjs.org/@altheia-xyz/mcp/-/mcp-0.0.2.tgz","fileCount":8,"unpackedSize":16707,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIC4qMJczwAm7FIZu2n96Jzt/X4qgbfQv/qX+W1GgA+eSAiEAmTff6Nc788Gg2uvgddto3e6HVgI7FuUQXDPK0gU8LCU="}]},"_npmUser":{"name":"altheia","email":"hello@altheia.xyz"},"directories":{},"maintainers":[{"name":"altheia","email":"hello@altheia.xyz"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.0.2_1778541796755_0.32037083623784857"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-09T15:37:14.737Z","modified":"2026-05-11T23:23:17.030Z","0.0.1":"2026-05-09T15:37:15.092Z","0.0.2":"2026-05-11T23:23:16.897Z"},"bugs":{"url":"https://github.com/altheia-xyz/altheia-sdk/issues"},"license":"Apache-2.0","homepage":"https://docs.altheia.xyz","keywords":["mcp","model-context-protocol","solana","ai","agent","altheia"],"repository":{"type":"git","url":"git+https://github.com/altheia-xyz/altheia-sdk.git","directory":"packages/mcp"},"description":"AI agents you can fire — Altheia MCP server. Connects Claude Desktop, Cursor, ChatGPT to your gated agent fleet.","maintainers":[{"name":"altheia","email":"hello@altheia.xyz"}],"readme":"# `@altheia-xyz/mcp`\n\n**AI agents you can fire — MCP server.**\n\n📖 Docs: [docs.altheia.xyz](https://docs.altheia.xyz)\n\nStandalone [MCP (Model Context Protocol)](https://modelcontextprotocol.io)\nserver that exposes [Altheia](https://altheia.xyz)'s policy + audit layer to\nany MCP-aware client (Claude Desktop, Cursor, ChatGPT, custom agents).\n\nThe LLM operates against your Altheia-registered agent through these tools.\nEvery action goes through Altheia's pre-flight policy check before the\nagent's wallet signs anything on-chain. The on-chain Swig session-key scope\nis the floor — even if the LLM ignores the gate, the chain refuses\nout-of-policy signatures.\n\n## Install + run\n\n```bash\nnpx -y @altheia-xyz/mcp\n```\n\nRequired env:\n\n| Var | Required | Default |\n|---|---|---|\n| `ALTHEIA_AGENT_ID` | yes | — |\n| `ALTHEIA_BACKEND` | no | `https://api.altheia.xyz` (defaults to prod — set only for self-hosting) |\n| `ALTHEIA_API_KEY` | yes (in production) | — |\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `altheia_check` | Synchronous policy decision; no execution, no audit row. Returns the `Decision` (`allowed`, `reason`, `audit_event_id`). |\n| `altheia_guard` | Pre-flight gate. Returns `ALLOWED:` or `DENIED:` summary; sets `isError: true` on deny so MCP-aware LLMs short-circuit cleanly. |\n| `altheia_report` | Log an action outcome to the audit trail. Best-effort. |\n| `altheia_policy` | Fetch the current policy in scope (per-asset caps, allowed programs, etc). |\n| `altheia_audit_query` | Query recent audit events. Supports `filter` (`all`/`allowed`/`denied`) + `limit` (1–100). |\n\n## Resources (read-only)\n\n| URI | Content |\n|---|---|\n| `altheia://agent/<id>` | AgentObject (status, on-chain refs, framework) |\n| `altheia://agent/<id>/policy` | Current PolicyObject |\n| `altheia://agent/<id>/audit` | Last 50 audit events, most recent first |\n\n## Claude Desktop config\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"altheia\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@altheia-xyz/mcp\"],\n      \"env\": {\n        \"ALTHEIA_AGENT_ID\": \"<uuid from your dashboard>\",\n        \"ALTHEIA_BACKEND\": \"https://api.altheia.xyz\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The five tools appear in any new chat. Try:\n*\"Check whether I can transfer 50 USDC, and if allowed, fetch my policy.\"*\n\n## Cursor config\n\n`.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"altheia\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@altheia-xyz/mcp\"],\n      \"env\": {\n        \"ALTHEIA_AGENT_ID\": \"<uuid>\",\n        \"ALTHEIA_BACKEND\": \"https://api.altheia.xyz\"\n      }\n    }\n  }\n}\n```\n\n## How an LLM should use these tools\n\n```\nUser: \"Swap 50 USDC to SOL with my agent.\"\n\nLLM:\n  1. altheia_guard({ type: \"swap\", amount: 50, asset: \"EPjF...Dt1v\" })\n     → \"ALLOWED: Action allowed. Proceed, then call altheia_report...\"\n  2. <run whatever execution tool>\n  3. altheia_report({ action, outcome: \"success\", audit_event_id })\n```\n\nIf guard returns `DENIED`, the LLM must abort. Even if it tries to skip the\ngate, the on-chain Swig scope rejects out-of-policy signatures.\n\n## Failure mode\n\nIf the Altheia backend is unreachable, `altheia_check` and `altheia_guard`\nfall back to the SDK's fail-open default (action allowed; on-chain substrate\nstays the floor). The audit trail catches up via the backend's reconciliation\ncron + Helius webhook retries once the backend recovers.\n\n## Build from source\n\n```bash\ncd packages/mcp\npnpm install\npnpm build\nALTHEIA_AGENT_ID=<uuid> node dist/cli.js  # ALTHEIA_BACKEND defaults to https://api.altheia.xyz\n```\n\n## Tests\n\n```bash\npnpm test\n```\n\n12 vitest exercising the full server through an in-memory client/server pair\n(no stdio overhead). Verifies: tool discovery, resource discovery,\n`altheia_check` allow/deny paths, `altheia_guard` `isError` semantics,\n`altheia_audit_query` URL + Bearer-header propagation, `altheia_policy`\nsuccess + error paths, agent metadata resource read.\n\n## Status\n\n`v0.0.2` — alpha. Mainnet ready (unaudited).\n\nLicense: Apache-2.0.\n","readmeFilename":"README.md"}