apex-mcp-server/docs/VECTOR.md

Vector MCP Server — Tool Reference

Overview

The Vector MCP Server exposes blockchain tools that AI agents can use to interact with the Vector network. All tools use the vector_ prefix and communicate with Vector via Ogmios (chain queries) and the submit API (transaction submission).

Prerequisites

1. A Vector wallet address (source of funds) — the tools below are keyless and take no mnemonic; signing happens separately via your local signer
2. Access to Vector network endpoints (Ogmios, submit API, Koios)
3. Node.js >= 14.0.0

Tools

vector_get_balance

Get ADA and token balances for any Vector address.

Parameters:

• address (string, required) — Vector address to check (addr1...)

Example prompt: "What's the balance of addr1qx..."

vector_get_utxos

List unspent transaction outputs for an address.

Parameters:

• address (string, required) — Address to query (addr1...)

Example prompt: "Show me the UTxOs at addr1qx..."

vector_build_send_apex

Build an unsigned transaction sending AP3X to a recipient (keyless — takes no key material). Sign the returned CBOR with your local signer, then broadcast with vector_submit_transaction.

Parameters:

• changeAddress (string, required) — Your wallet address; source of funds and change (addr1...)
• recipientAddress (string, required) — Recipient address (addr1...)
• amount (number, required) — Amount of AP3X to send (minimum 1)
• metadata (string, optional) — Transaction metadata in JSON format

Example prompt: "Send 5 AP3X to addr1qy..."

vector_build_send_tokens

Build an unsigned transaction sending Vector native tokens (keyless — takes no key material). Sign the returned CBOR with your local signer, then broadcast with vector_submit_transaction.

Parameters:

• changeAddress (string, required) — Your wallet address; source of funds and change (addr1...)
• recipientAddress (string, required) — Recipient address (addr1...)
• policyId (string, required) — Token policy ID
• assetName (string, required) — Asset name (can be empty)
• amount (string, required) — Amount of tokens to send
• adaAmount (number, optional) — AP3X to include with tokens

Example prompt: "Send 100 of token with policy abc123... to addr1qy..."

vector_build_transaction

Build an unsigned multi-output transaction with metadata (keyless, never submits). Sign the returned CBOR with your local signer, then broadcast with vector_submit_transaction.

Parameters:

• changeAddress (string, required) — Your wallet address; source of funds and change (addr1...)
• outputs (array, required) — Array of { address, lovelace, assets? } objects
• metadata (string, optional) — JSON metadata (attached under label 674)

Example prompt: "Build a transaction sending 5 AP3X to addr1qx... and 3 AP3X to addr1qy..."

vector_dry_run

Simulate a transaction without submitting — returns fee estimate and validation (keyless).

Parameters:

• txCbor (string, optional) — Hex CBOR of a built transaction to evaluate
• outputs (array, optional) — If no txCbor, build a TX from these outputs and evaluate
• changeAddress (string, optional) — Your wallet address; required when building from outputs
• metadata (string, optional) — JSON metadata when building from outputs

Example prompt: "How much would it cost to send 10 AP3X to addr1qx...?"

vector_get_transaction_history

Get transaction history for an address via Koios indexed queries.

Parameters:

• address (string, required) — Address to query (addr1...)
• limit (number, optional) — Number of transactions (default: 20, max: 50)
• offset (number, optional) — Pagination offset (default: 0)

Example prompt: "Show me recent transactions for addr1qx..."

vector_build_deploy_contract

Build an unsigned transaction deploying a Plutus/Aiken smart contract by locking funds at its script address (keyless). Sign the returned CBOR with your local signer, then broadcast with vector_submit_transaction.

Parameters:

• changeAddress (string, required) — Your wallet address; source of funds and change (addr1...)
• scriptCbor (string, required) — Compiled script CBOR hex
• scriptType (string, required) — "PlutusV1", "PlutusV2", or "PlutusV3"
• initialDatum (string, optional) — Datum CBOR hex (default: void d87980)
• lovelaceAmount (number, optional) — AP3X to lock in lovelace (default: 2 AP3X)

Example prompt: "Deploy this smart contract with 5 AP3X locked"

vector_build_interact_contract

Build an unsigned transaction interacting with a deployed smart contract — lock funds or spend from it (keyless). Sign the returned CBOR with your local signer, then broadcast with vector_submit_transaction.

Parameters:

• changeAddress (string, required) — Your wallet address; source of funds, change, and the required signer for spends (addr1...)
• scriptCbor (string, required) — Compiled script CBOR hex
• scriptType (string, required) — "PlutusV1", "PlutusV2", or "PlutusV3"
• action (string, required) — "spend" or "lock"
• redeemer (string, optional) — Redeemer CBOR hex (for spend, default: void)
• datum (string, optional) — Datum CBOR hex (for lock, default: void)
• lovelaceAmount (number, optional) — Lovelace to lock (for lock)
• utxoRef (object, optional) — { txHash, outputIndex } for specific UTxO (for spend)
• assets (object, optional) — Native assets for lock: { "unit": "quantity" }

Example prompt: "Collect funds from the escrow contract at addr1..."

Safety Controls

The tools above are keyless and take no key material, so the server no longer enforces spend limits on them. Spend policy is enforced by your local signer when it signs the CBOR these tools return — see the security notice in the repo README and docs/architecture/non-custodial-split.md.

VECTOR_SPEND_LIMIT_PER_TX / VECTOR_SPEND_LIMIT_DAILY / VECTOR_AUDIT_LOG_PATH still govern the server's remaining custodial tool families (agent registry, self-improvement) until their own keyless migration lands.

Network Endpoints

Service	URL	Protocol
Ogmios	ogmios.vector.testnet.apexfusion.org	HTTP JSON-RPC + WebSocket
Submit API	submit.vector.testnet.apexfusion.org/api/submit/tx	HTTP POST (CBOR)
Koios	koios.vector.testnet.apexfusion.org	REST API
Explorer	vector.testnet.apexscan.org	Web UI

Error Handling

All tools return helpful error messages with troubleshooting tips. Common issues:

• Insufficient balance — Ensure the wallet at changeAddress has enough AP3X for the transaction + fees
• Connection failed — Verify Ogmios endpoint is reachable
• Invalid address — Vector addresses start with addr1