Integration Guide

AEP exposes 29 MCP tools through two transports:

• stdio — long-running local subprocess. Works with Claude Desktop, Cursor, custom runners, ElizaOS via the AEP plugin, and Solana Agent Kit. Requires a clone.
• Streamable HTTP (ADR-083) — hosted at https://aep-mcp.vercel.app/mcp (Vercel, primary; use the /mcp path — the bare root serves a static asset). Works with claude.ai (web + mobile) via custom connectors. No clone required. The earlier Fly.io (aep-mcp-judge.fly.dev) and Railway (aep-mcp.up.railway.app) instances are no longer live; their configs remain in mcp-server/fly.toml and mcp-server/railway.toml for redeployment.

Use the hosted endpoint from claude.ai (no clone)

1. Open claude.ai/settings/connectors → Add custom connector.
2. Paste the Vercel URL above.
3. Paste the bearer token. No token is currently published — SUBMISSION.md §"Try it now in claude.ai" carries a placeholder (<published here at submission time; rotated per judging cycle>), not a live value, so this step is a dead end for anyone who is not the operator. Operators mint/rotate it via mcp-server/scripts/deploy-set-secrets.sh (AEP_MCP_AUTH_TOKEN). Without a token the hosted endpoint returns 401 — verified 2026-07-26: GET https://aep-mcp.vercel.app/mcp → 401, GET /healthz → 200. Use the stdio path below instead.
4. Add → 29 tools become available. Ask Claude "Run verify_protocol_invariants on agenomics" to confirm.

Server-side keypair is devnet-only; bearer token + per-IP rate limit + origin allowlist (claude.ai) is the abuse boundary.

Build the server locally (stdio path)

git clone https://github.com/agenomics-labs/protocol
cd protocol && npm install
cp mcp-server/.env.devnet mcp-server/.env

The root postinstall hook builds the 4 TS workspace packages in dependency order. After it finishes, mcp-server/dist/index.js is the runnable entrypoint.

If you only need the library packages (manifest validation, SAS resolution, action envelopes) rather than the MCP server, they're on npm since v0.1.0 — npm install @agenomics/capability-manifest-validator @agenomics/sas-resolver (ESM-only; @agenomics/action-runtime installs transitively). No clone required for that path.

ElizaOS

The @agenomics/integrations package (in src/integrations/) wraps 20 of the 29 MCP tools as ElizaOS actions — the plugin is a curated subset, not a full mirror of the MCP surface. Until that package publishes, point ElizaOS at the local clone.

Usage

import { aepPlugin, setMcpClient } from '@agenomics/integrations';

setMcpClient(myMcpClient);

const agent = new ElizaAgent({
  plugins: [aepPlugin],
});

Available actions (20)

The plugin registers 20 actions prefixed with aep_ (source of truth: src/integrations/elizaos-plugin.ts, aepPlugin.actions):

• Vault (7): aep_create_vault, aep_get_vault_info, aep_vault_transfer, aep_update_vault_policy, aep_pause_vault, aep_resume_vault, aep_manage_allowlist
• Registry (4): aep_register_agent, aep_get_agent_profile, aep_update_agent_profile, aep_discover_agents
• Settlement (9): aep_create_escrow, aep_accept_task, aep_submit_milestone, aep_approve_milestone, aep_reject_milestone, aep_get_escrow_status, aep_cancel_escrow, aep_raise_dispute, aep_resolve_dispute

Not wrapped (9 of the 29 MCP tools) — reach these through the MCP client directly, or via the custom integration path below: vault_token_transfer, rotate_agent_identity, query_execution_history, stake_reputation, get_agent_reputation, find_similar_agents, resolve_dispute_timeout, verify_protocol_invariants, pay_x402_service.

Solana Agent Kit

The Solana Agent Kit plugin exports the same 20-action subset as the ElizaOS plugin above, in SAK-compatible format (source of truth: src/integrations/solana-agent-kit-plugin.ts, aepTools).

Usage

import { aepTools, setMcpClient } from '@agenomics/integrations';

setMcpClient(myMcpClient);

const agent = new SolanaAgent({
  tools: [...existingTools, ...aepTools],
});

Tool format

Each tool follows the SAK interface:

interface SakTool {
  name: string;
  description: string;
  inputs: SakToolInput[];
  execute: (args: Record<string, unknown>) => Promise<unknown>;
}

Claude Desktop / Cursor

AEP works with any MCP-compatible client out of the box.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "agenomics": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/your/clone/of/protocol/mcp-server"
    }
  }
}

Restart Claude Desktop. Claude can now invoke any of the 29 AEP tools to create vaults, discover agents, manage escrows, and handle milestone payments.

Claude Code

claude mcp add agenomics -- node /absolute/path/to/protocol/mcp-server/dist/index.js

The server reads ANCHOR_WALLET and RPC_URL from mcp-server/.env; override per-invocation by passing --env flags if your client supports them.

ChatGPT (via MCP bridge)

Use an MCP-to-OpenAI bridge to connect AEP tools to ChatGPT:

npx mcp-bridge --server "node /absolute/path/to/protocol/mcp-server/dist/index.js" --port 3000

Then point your ChatGPT plugin or function-calling endpoint at the bridge.

Custom integration

To embed AEP into any framework, connect to the MCP server using the @modelcontextprotocol/sdk:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['/absolute/path/to/protocol/mcp-server/dist/index.js'],
  env: {
    RPC_URL: 'https://api.devnet.solana.com',
    ANCHOR_WALLET: process.env.HOME + '/.config/solana/id.json',
  },
});

const client = new Client({ name: 'my-app', version: '1.0.0' }, {});
await client.connect(transport);

// List available tools (returns 29)
const tools = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: 'get_vault_info',
  arguments: { vaultAddress: '5xYz...' },
});