{
  "markdown": "# Vector MCP Server\n\nMCP (Model Context Protocol) server for **Vector** - the Apex Fusion eUTXO L2. Enables AI agents (Claude, GPT, Gemini, or any MCP client) to interact with Vector natively: query balances, send transactions, deploy and interact with smart contracts, manage on-chain agent identities, and submit protocol improvement proposals.\n\nBuilt on [Ogmios](https://ogmios.dev/) + [Koios](https://www.koios.rest/) - no Blockfrost dependency.\n\n**Vector mainnet is live.** Full guides: [Vector AI documentation](https://apex-fusion.github.io/vector-ai-documentation/).\n\n## Hosted servers - no install\n\nHosted instances run on both networks, exposing all 24 tools:\n\n| Network | Endpoint |\n|---------|----------|\n| Mainnet | `https://mcp.vector.mainnet.apexfusion.org/mcp` |\n| Testnet | `https://mcp.vector.testnet.apexfusion.org/mcp` |\n\n> **Deployment status: both networks are current.** Both hosted instances run today's\n> completed migration: testnet since the 2026-07-31 morning merges (auto-deployed from\n> `main`), mainnet since a deliberate cutover deploy the same day (see\n> [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md), section\n> 11, \"Rollout\", for the full history). **Both hosted instances are open access - no bearer\n> token is required to connect.** Callers are admitted anonymously with per-IP rate limiting.\n> That is an access-control property, and it is separate from custody: neither instance\n> accepts a mnemonic from any caller, with or without a token. Self-hosted deployments can\n> still gate access with `MCP_AUTH_TOKENS` - see [Configuration](#configuration).\n\n> **Transport: Streamable HTTP only, as of 2.0.0.** The legacy SSE pair (`/sse` +\n> `/messages`), deprecated by the MCP spec (2026-07-28 revision), was removed in this release -\n> those paths now answer 404. Every client connects to `/mcp`, the endpoint the table above\n> lists. This is a breaking change for SSE clients: reconnect with `--transport http` and the\n> `/mcp` URL (below). The server also answers any-origin CORS (browser MCP clients are\n> first-class callers) and exposes an unauthenticated `GET /health` liveness probe.\n> **This describes the code** - each hosted instance serves it once this release deploys there\n> (testnet automatically on push to `main`, mainnet on a deliberate cutover dispatch).\n\nConnect from Claude Code in one command. No token needed for the hosted instances.\n\n```bash\nclaude mcp add --transport http vector-mcp https://mcp.vector.mainnet.apexfusion.org/mcp\n```\n\nSwap in the testnet host to connect to testnet instead. Self-hosting (below) gives every\ncaller open access to your own instance unless you set `MCP_AUTH_TOKENS`.\n\n> **Security notice: the non-custodial migration is complete, in this codebase and on both\n> hosted instances, as of the 2026-07-31 cutover deploy.** No tool in this repository accepts a\n> mnemonic, private key, or any other key material. Every `build_*` tool constructs an unsigned\n> transaction from a wallet *address* only, and every signing operation happens locally on your\n> own machine, through the local signer companion. Broadcast the signed result with\n> `vector_submit_transaction` - your seed phrase never leaves your machine, and no server\n> running this release ever holds one. This is enforced mechanically in the code, not just by\n> convention: the builder's custody boundary test scans every source file for key-material\n> vocabulary against an allowlist that is now empty and pinned at size zero, so a future change\n> cannot silently reintroduce a mnemonic parameter without failing that test by name.\n> **This describes this release and the 2026-07-31 deploy specifically** - a later deploy is a\n> separate operational action, not automatically covered by this notice; see the deployment\n> status note above and\n> [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md) for the\n> full rollout history.\n\nSelf-hosting instructions are below.\n\n## Local signer (non-custodial path)\n\n`packages/signer` is a local MCP server that holds your key and signs transactions locally\ninstead of handing your mnemonic to a shared host. It has **no network access at all**:\nstdio transport only, no Provider, no egress, so a key given to it never reaches a shared server\nor your model provider. Four tools: `vector_signer_get_address`, `vector_signer_decode_transaction`,\n`vector_signer_sign`, `vector_signer_get_spend_limits`.\n\n**In this codebase, this signer is the single signing point for every family the builder\nexposes.** The full non-custodial flow is live in this release for all of them:\n`vector_signer_get_address` → `build_*` → `vector_signer_sign` → `vector_submit_transaction` →\n`vector_await_transaction`. No step in that chain puts a mnemonic in front of a server running\nthis code, or your model provider, for any tool. The build → submit → await half is E2E-proven\non Vector testnet across the wallet/tx, smart-contract, agent-registry, and self-improvement\nfamilies, including the first keyless-built proposal submission the deployed self-improvement\nmodule validator has ever accepted; see\n[`packages/signer/README.md`](packages/signer/README.md#known-limitations) for exactly what that\ntesting does and does not exercise on the signer's side. **This describes the code, not every\ndeployment of it** - see the deployment status note above.\n\nSee [`packages/signer/README.md`](packages/signer/README.md) for configuration, tools, and known\nlimitations.\n\n## Features\n\n- **Wallet & queries** - balances, UTxOs, and transaction history for any address (no key material)\n- **Keyless transaction building** - build unsigned AP3X/token/multi-output transactions and contract interactions; sign locally, broadcast via submit\n- **Smart contracts** - deploy Plutus/Aiken validators, lock and spend UTxOs at script addresses (keyless)\n- **Agent registry** - register, discover, update, transfer, and deregister on-chain AI agent identities via soulbound NFTs (keyless - build, sign locally, broadcast)\n- **Agent messaging** - send on-chain messages between agents via TX metadata (keyless)\n- **Self-Improvement Module** - browse, submit, critique, and endorse improvement proposals; the on-chain module is live on Vector mainnet, and every write tool is keyless in this codebase\n- **Safety controls** - per-identity rate limiting; spend limits for every family are enforced by the local signer, per user - the server holds no spend-limit state of its own\n- **Streamable HTTP transport** - the modern MCP transport at `/mcp`, with any-origin CORS for browser clients and an unauthenticated `GET /health` probe (the legacy SSE pair was removed in 2.0.0)\n\n## MCP Tools (24)\n\n### Wallet & Queries\n\n| Tool | Description |\n|------|-------------|\n| `vector_get_balance` | Get AP3X and token balances for any address |\n| `vector_get_utxos` | List UTxOs for an address |\n| `vector_get_transaction_history` | Get transaction history for an address |\n\n### Transactions\n\n| Tool | Description |\n|------|-------------|\n| `vector_build_send_apex` | Build an unsigned AP3X transfer (keyless - sign with the local signer) |\n| `vector_build_send_tokens` | Build an unsigned native-token transfer (keyless) |\n| `vector_build_transaction` | Build an unsigned multi-output transaction (keyless, never submits) |\n| `vector_dry_run` | Simulate a transaction without submitting - estimate fees and validate |\n| `vector_submit_transaction` | Broadcast an already-signed transaction (for example one signed by the local signer) |\n| `vector_await_transaction` | Wait for a submitted transaction to be confirmed on-chain |\n\n### Smart Contracts\n\n| Tool | Description |\n|------|-------------|\n| `vector_build_deploy_contract` | Build an unsigned deployment of a Plutus V1/V2/V3 or Aiken validator (keyless) |\n| `vector_build_interact_contract` | Build an unsigned lock or spend at a script address, with a redeemer (keyless) |\n\n### Agent Registry\n\n| Tool | Description |\n|------|-------------|\n| `vector_build_register_agent` | Build an unsigned agent registration - mints a soulbound identity NFT and locks a 10 AP3X deposit (keyless) |\n| `vector_discover_agents` | Discover registered agents, filter by capability or framework (no wallet needed) |\n| `vector_get_agent_profile` | Get an agent's full profile by DID (no wallet needed) |\n| `vector_build_update_agent` | Build an unsigned update to an agent's name, description, capabilities, framework, or endpoint (keyless) |\n| `vector_build_transfer_agent` | Build an unsigned transfer of agent ownership to a new address (keyless) |\n| `vector_build_deregister_agent` | Build an unsigned deregistration - burns the identity NFT and returns the 10 AP3X deposit (keyless) |\n| `vector_build_message_agent` | Build an unsigned on-chain message to an agent via TX metadata (label 674) (keyless) |\n\n### Self-Improvement Module\n\n| Tool | Description |\n|------|-------------|\n| `vector_self_improvement_browse` | Browse improvement proposals, critiques, and endorsements |\n| `vector_self_improvement_analyze_metrics` | Proposal metrics: activity, adoption rate, treasury health, engagement |\n| `vector_build_self_improvement_proposal_lock` | Build an unsigned proposal-stake lock (step 1 of 2, keyless) |\n| `vector_build_self_improvement_proposal_spend` | Build an unsigned proposal submission - spends the lock and mints the proposal and activity tokens (step 2 of 2, keyless). Two transactions, agent-orchestrated. |\n| `vector_build_self_improvement_critique` | Build an unsigned critique on a proposal - support, oppose, or propose amendments (keyless) |\n| `vector_build_self_improvement_endorse` | Build an unsigned endorsement of a proposal by staking AP3X (keyless) |\n\nAgent DIDs follow the format: `did:vector:agent:{policyId}:{nftAssetName}`\n\nExample non-custodial flow for a registry op: `vector_build_register_agent` →\n`vector_signer_sign` → `vector_submit_transaction` → `vector_await_transaction`.\n\n## Self-hosting\n\n### 1. Install and build\n\nRequires Node.js >= 22 (matches `engines` in every `package.json` and the Dockerfile's\n`node:22-alpine` base).\n\n```bash\nnpm install\nnpm run build\n```\n\n**Dependency advisories.** `npm audit` currently reports 1 low-severity advisory: an `esbuild`\narbitrary-file-read issue that only triggers via its own Windows dev server, reachable solely\nthrough `tsup` (a build-time-only dependency, absent from the production image, which installs\nwith `npm ci --omit=dev`). As of 2026-07-31 this tree carried 44 advisories, including 1\ncritical (`tar`, GHSA-23hp-3jrh-7fpw) that arrived because `@cardano-sdk/crypto` - pulled in\ntransitively through `@lucid-evolution/lucid` - declared the entire `npm` CLI package as a\nruntime dependency. That dependency was dead weight: `@cardano-sdk/crypto`'s own published code\nnever requires `npm`, and neither `npm` nor `tar` appears anywhere in this server's built\nbundle. Regenerating the lockfile picked up a newer `@cardano-sdk/crypto` release that dropped\nthe stray dependency outright, clearing all 43 of those advisories without any override needed;\n`package.json` also carries a defensive `overrides` pin on `tar` and `brace-expansion` against\nfuture regressions, though it is not what resolved this one.\n\n### 2. Configure environment (optional)\n\n```bash\ncp .env.example .env\n# Edit .env with your endpoint URLs (defaults point to Vector testnet; mainnet URLs below)\n```\n\nEvery `build_*` tool is keyless: it takes a wallet address, never a mnemonic. No tool call\nagainst this server ever needs a mnemonic parameter, for any family - see the security notice\nabove.\n\n### 3. Run\n\n```bash\nnpm start\n# Server listens on port 3000 (configurable via PORT env var)\n```\n\nConnect:\n\n```bash\nclaude mcp add --transport http vector-mcp http://localhost:3000/mcp\n```\n\nAdd `--header \"Authorization: Bearer <your-token>\"` if you set `MCP_AUTH_TOKENS`. A liveness\nprobe is at `GET /health` - unauthenticated, returns `{\"status\":\"ok\",\"version\":\"<version>\"}`.\n\nIf this instance will be reachable by anyone but you, set `MCP_AUTH_TOKENS` first - see [Configuration](#configuration) below.\n\n### 4. Add to Claude Desktop\n\nAdd to your Claude Desktop MCP config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"vector\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/vector-mcp-server/packages/builder/build/index.js\"],\n      \"env\": {\n        \"VECTOR_OGMIOS_URL\": \"https://ogmios.vector.testnet.apexfusion.org\",\n        \"VECTOR_SUBMIT_URL\": \"https://submit.vector.testnet.apexfusion.org/api/submit/tx\",\n        \"VECTOR_KOIOS_URL\": \"https://koios.vector.testnet.apexfusion.org/\",\n        \"VECTOR_EXPLORER_URL\": \"https://vector.testnet.apexscan.org\"\n      }\n    }\n  }\n}\n```\n\nFor mainnet, use the mainnet endpoint table below. (No local setup needed if you use the hosted servers above.)\n\n### Docker\n\n```bash\nnpm run build\ndocker build -t vector-mcp .\ndocker run -p 3000:3000 vector-mcp\n```\n\nIf this instance will be reachable by anyone but you, set `MCP_AUTH_TOKENS` first - see [Configuration](#configuration) below (`docker-compose.yml` in this repo binds `127.0.0.1` by default; the command above does not).\n\n## Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | HTTP server port | `3000` |\n| `VECTOR_OGMIOS_URL` | Ogmios HTTP JSON-RPC endpoint | `https://ogmios.vector.testnet.apexfusion.org` |\n| `VECTOR_KOIOS_URL` | Koios REST API endpoint | `https://v2.koios.vector.testnet.apexfusion.org/` |\n| `VECTOR_SUBMIT_URL` | Transaction submit API | `https://submit.vector.testnet.apexfusion.org/api/submit/tx` |\n| `VECTOR_EXPLORER_URL` | Block explorer base URL | `https://vector.testnet.apexscan.org` |\n| `VECTOR_RATE_LIMIT_PER_MINUTE` | Max tool calls per minute, per identity (min `1`) | `60` |\n| `VECTOR_MCP_SESSION_IDLE_MS` | `/mcp` session idle timeout before the reaper closes it, in ms (min `100`) | `600000` (10 min) |\n| `VECTOR_MCP_SESSION_SWEEP_MS` | How often the `/mcp` idle reaper sweeps, in ms (min `100`) | `60000` (1 min) |\n| `VECTOR_MCP_MAX_SESSIONS_PER_IDENTITY` | Max concurrent `/mcp` sessions per identity before the oldest is evicted (min `1`) | `32` |\n| `MCP_AUTH_TOKENS` | Bearer tokens that may call this server. Comma-separated; each entry is `label:token` or a bare token. **When unset, the server is open to anyone who can reach it.** | _(unset - auth disabled)_ |\n\nThe four numeric knobs above fail loudly at startup on a malformed value: anything that is not\na plain integer, or is below its listed minimum, raises a startup error naming the variable and\nthe value it got, rather than silently falling back to some other behavior (an unparseable rate\nlimit silently disabling rate limiting, for example).\n\nThis server has no spend-limit or audit-log configuration of its own: it holds no key material\nfor any family, so it has nothing left to limit. Every spend limit, and the audit log recording\nit, lives in your local signer instead - see `VECTOR_SIGNER_SPEND_LIMIT_PER_TX` /\n`VECTOR_SIGNER_SPEND_LIMIT_DAILY` / `VECTOR_SIGNER_AUDIT_LOG_PATH` in\n[`packages/signer/README.md`](packages/signer/README.md#configuration).\n\n> **Running a public instance?** Set `MCP_AUTH_TOKENS` to gate access to known callers, each\n> with its own rate-limit budget. Note that the server answers any-origin CORS by design: with\n> auth unset, any web page a browser user visits can drive your instance from JavaScript,\n> sharing that user's per-IP rate-limit bucket - one more reason a public instance should set\n> `MCP_AUTH_TOKENS`. With `MCP_AUTH_TOKENS` unset, callers are admitted\n> anonymously with per-client-IP rate limits; the deployment's reverse proxy supplies the\n> client address via the rightmost X-Forwarded-For entry. Tracked identities are capped (LRU);\n> eviction resets a bucket's budget - a memory bound, not a security boundary, since an\n> attacker rotating enough source IPs can still defeat per-IP limiting at a tier only the\n> reverse proxy or network layer can police. `/mcp` sessions get the same per-identity\n> treatment: idle sessions are reaped (`VECTOR_MCP_SESSION_IDLE_MS`, swept every\n> `VECTOR_MCP_SESSION_SWEEP_MS`), and concurrent sessions per identity are capped\n> (`VECTOR_MCP_MAX_SESSIONS_PER_IDENTITY`) - see the Configuration table above for defaults and\n> minimums.\n\n> **Malformed values fail loudly.** The server refuses to start if\n> `MCP_AUTH_TOKENS` contains an empty token, a token with embedded whitespace, a\n> duplicate token, or a value where every comma-separated entry is blank (e.g. a\n> stray `,,,`). Each case raises a startup error that names the problem but never\n> echoes a token value. Commas delimit entries and cannot be escaped, so generate\n> tokens from a comma-free charset (hex / base64url / alphanumeric).\n\n> **Error responses do not echo configured endpoints.** This covers every failure\n> mode a network call can produce, not just an HTTP-level rejection: a DNS\n> failure, a dropped connection, and a malformed (non-JSON) response body are all\n> sanitised the same way an ordinary `4xx`/`5xx` status is - the underlying HTTP\n> client is the platform's native `fetch`, chosen in part because its own errors\n> do not embed the request URL the way some polyfills do. A failed Ogmios or\n> Koios query is this server's own infrastructure problem, not something the\n> caller can act on - it is reported by service name and status only, for\n> example \"Ogmios request failed (queryLedgerState/utxo): 503 Service\n> Unavailable\" or, for a connection failure, \"...: network error\". A rejected\n> transaction submission is different: the ledger's verdict on the CALLER'S OWN\n> transaction (a bad input, an unmet script condition, a fee too small) stays in\n> the response, since it is the feedback loop an agent needs to self-correct after\n> build → sign → submit - only URL-shaped content is scrubbed out of it first, for\n> example \"Transaction submission rejected (400 Bad Request):\n> ValueNotConservedUTxO...\". A NETWORK failure to even reach the submit API is\n> reported as an infrastructure failure instead (\"...: network error\"), never\n> worded as a ledger rejection, since nothing looked at the transaction at all.\n> Neither case ever echoes the configured `VECTOR_OGMIOS_URL` / `VECTOR_KOIOS_URL`\n> / `VECTOR_SUBMIT_URL` value itself, and full unscrubbed detail always goes to\n> the server's own `console.error` log for operators. **Known limit:** the\n> submission-rejection scrub removes http(s) URLs and the three endpoints above\n> by name - a rejection body that happens to name some other internal hostname\n> passes through unscrubbed, bounded by a 2000-character cap.\n\n### Mainnet endpoints\n\n| Variable | Mainnet value |\n|----------|---------------|\n| `VECTOR_OGMIOS_URL` | `https://ogmios.vector.mainnet.apexfusion.org` |\n| `VECTOR_SUBMIT_URL` | `https://submit.vector.mainnet.apexfusion.org/api/submit/tx` |\n| `VECTOR_KOIOS_URL` | `https://v2.koios.vector.mainnet.apexfusion.org/` |\n| `VECTOR_EXPLORER_URL` | `https://vector.apexscan.org/en/` |\n\n## Testing\n\n```bash\nnpm run test:unit\n```\n\nNo wallet, no network - pure logic only (CBOR encode/decode assertions).\n\n```bash\nnpm run test:smoke\n```\n\nBuilds the server, boots it, and asserts the exposed tool inventory matches the checked-in snapshot. No wallet, no external network. CI runs this and `test:unit` on every PR.\n\n```bash\necho \"your mnemonic words here\" > packages/builder/mnemonic.txt\nnpm run test:integration\n```\n\nRequires `mnemonic.txt` in `packages/builder/` containing a **funded Vector testnet** mnemonic. Covers the core tools end-to-end against Vector testnet, including the full agent lifecycle: register, discover, profile, update, transfer, message, and deregister (all keyless now: build → sign → submit → await per step). Also runs `keyless-build.test.ts`, `registry-keyless.test.ts`, and `self-improvement-keyless.test.ts` - tier-1 suites needing no mnemonic at all, each building unsigned transactions against live public data only (`vector_build_send_tokens` is covered offline, by unit tests and the legacy suite above; `self-improvement-keyless.test.ts` covers critique, endorse, and proposal-lock builds, plus a not-found rejection path on proposal-spend). Set `VECTOR_E2E_SUBMIT=1` to additionally run each family's gated end-to-end suite, fully on-chain: `keyless-e2e.test.ts` lands one real self-send (~0.16 AP3X fee); `registry-e2e.test.ts` runs a full register → update → deregister agent lifecycle (the 10 AP3X deposit round-tripped exactly, fees only as net cost); `self-improvement-e2e.test.ts` locks and spends a real improvement proposal through the deployed module validator, then critiques and endorses it (≈48 AP3X in stakes and module minimums, plus six transaction fees, one-way - the stakes are locked by the module's own design, not lost). Set `LEGACY_FULL=1` to additionally exercise the same self-improvement lock → spend sequence inside `run.test.ts` itself (off by default, since `self-improvement-e2e.test.ts` already proves that exact path). Never runs in CI.\n\n```bash\nnpm run test:smoke:signer\n```\n\nBuilds the local signer (`packages/signer`), boots it over stdio, and exercises all four of\nits tools, including the fail-closed audit-write-failure path. No wallet, no network. CI runs\nthis on every PR alongside the two smoke tests above.\n\n```bash\nexport VECTOR_SIGNER_MNEMONIC_FILE=/absolute/path/to/testnet-mnemonic.txt\nnpm run test:integration:signer\n```\n\nRequires a **funded Vector testnet** wallet. Builds a real unsigned transaction the way the\nhosted builder does (no key), then has the local signer decode, policy-check, and sign it\nagainst live chain data. **Never submits.** Never runs in CI. See\n[`packages/signer/README.md`](packages/signer/README.md#testing).\n\n## Architecture\n\n```\n┌──────────────────────┐             ┌──────────────────────────┐\n│  Claude / GPT / etc. │◄───────────►│  vector-mcp-server       │\n│  (any MCP client)    │    /mcp     │                          │\n└──────────────────────┘             │  ┌────────────────────┐  │\n                                     │  │ Rate Limiter        │  │\n                                     │  │ (60 calls/min)      │  │\n                                     │  └────────┬───────────┘  │\n                                     │           │               │\n                                     │  ┌────────▼───────────┐  │\n                                     │  │ Lucid + Ogmios     │  │\n                                     │  │ Provider            │  │\n                                     │  └────────┬───────────┘  │\n                                     │           │               │\n                                     │  ┌────────▼───────────┐  │\n                                     │  │ Ogmios / Koios /   │  │\n                                     │  │ Submit API          │  │\n                                     │  └────────────────────┘  │\n                                     └──────────────────────────┘\n```\n\nNo safety layer sits between the rate limiter and the provider: this server holds no key\nmaterial for any family, so it has no spend limits of its own left to enforce. Every spend\nlimit lives in your local signer instead.\n\n## About Vector\n\nVector is Apex Fusion's eUTXO L2, running Cardano mainnet parameters (Conway era, Plutus V3). Sub-1-second optimistic finality and deterministic fees make it a natural chain for AI agent workloads. Mainnet is live.\n\n- **Docs:** https://apex-fusion.github.io/vector-ai-documentation/\n- **Explorer (mainnet):** https://vector.apexscan.org/en/\n- **Explorer (testnet):** https://vector.testnet.apexscan.org\n- **Apex Fusion:** https://apexfusion.org\n",
  "bytes": 23643,
  "sha": "2693e2314300d690933f60c0d51345e50492541afed0aceab8a480c7c1366a24",
  "repo_slug": "apex-fusion/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_apex_fusion_vector_b792ad55/readme"
}