Integrating AgentVault

What is the shortest path to a working implementation?

Two integration paths

AgentVault provides two integration paths: a direct client integration path and an MCP-based tool integration path. The TypeScript client library is lower-level and gives full control over session lifecycle. The MCP server is higher-level and designed for agents that already speak the MCP protocol. The examples below show the current minimal implementation path. Production integrations may wrap token handoff and session coordination inside higher-level agent or application channels.

Use the client library when you are building a custom agent runtime, need fine-grained control over contract construction and session polling, or want to embed AgentVault calls directly in application code.

Use the MCP server when your agent framework already supports MCP tools, you want to expose AgentVault coordination as a tool the agent can call, or you need both INITIATE and RESPOND modes without managing session state manually.

TypeScript client: minimal working example

The agentvault-client package is a standalone fetch-based library with no framework dependencies. Install it from the repository: 

npm install github:vcav-io/agentvault#main --workspace=packages/agentvault-client

The package is not yet on npm. Install directly from the repository, or use a file: dependency if you have a local checkout.

Initiator side

The initiator creates the session, submits their input, and obtains the responder's join credentials for handoff: 

import {
  createAndSubmit,
  pollUntilDone,
} from 'agentvault-client';
import {
  buildRelayContract,
  computeRelayContractHash,
} from 'agentvault-client/relay-contracts';

// 1. Build a contract from a bundled session template
const contract = buildRelayContract('COMPATIBILITY', [
  'agent-alice',
  'agent-bob',
]);

// 2. Create session and submit initiator input
const config = { relay_url: 'http://localhost:3100' };
const result = await createAndSubmit(
  config,
  contract,
  { context: 'Alice private context here' },
  'agent-alice',
);

// result contains:
//   sessionId, contractHash,
//   responderSubmitToken, responderReadToken,
//   initiatorReadToken

// 3. Transmit responder credentials to Bob
//    through an authenticated application channel
// Bob needs: sessionId, contractHash,
//   responderSubmitToken, responderReadToken

// 4. Poll until done
const output = await pollUntilDone(
  config,
  result.session_id,
  result.initiator_read_token,
);
// output.state === 'COMPLETED' | 'ABORTED'
// output.receipt contains the signed receipt
// output.output contains the bounded signal

Responder side

The responder joins an existing session, verifies the contract hash, and waits for the result: 

import { joinAndWait } from 'agentvault-client';

// Credentials received from initiator
const output = await joinAndWait(
  { relay_url: 'http://localhost:3100' },
  sessionId,
  responderSubmitToken,
  responderReadToken,
  expectedContractHash, // relay verifies server-side
  { context: 'Bob private context here' },
  'agent-bob',
);

if (output.state === 'COMPLETED') {
  console.log('Signal:', output.output);
  console.log('Receipt:', output.receipt);
}

The expectedContractHash parameter is critical: the relay verifies it matches the session's actual contract hash and rejects with CONTRACT_MISMATCH if not. This prevents silent contract substitution at join time — the responder confirms they are joining the session they agreed to.

Contract builders

The client provides two contract-building functions:

buildRelayContract(purpose, participants) — builds a full contract from a bundled session template with the output schema embedded inline. Available purpose codes: COMPATIBILITY, MEDIATION.

buildRelayContractWithSchemaRef(purpose, participants, opts?) — builds a contract that references the schema by hash rather than embedding it. The relay performs a registry lookup. Use this when you want schema reuse without duplicating the full schema in every contract. Optional opts.policyHash overrides the default enforcement policy hash. 

import {
  buildRelayContractWithSchemaRef,
} from 'agentvault-client/relay-contracts';

// Schema-by-reference — relay looks up by hash
const contract = buildRelayContractWithSchemaRef(
  'MEDIATION',
  ['agent-alice', 'agent-bob'],
  { policyHash: 'custom-policy-hash-here' },
);

MCP server

The agentvault-mcp-server package exposes AgentVault operations as MCP tools. It supports two session modes:

INITIATE mode — the agent creates a session, submits its input, sends an invite to the peer, and polls for the result. The MCP server manages the full lifecycle.

RESPOND mode — the agent listens for incoming invites, accepts or declines them, submits input to accepted sessions, and returns the result. Requires the AFAL HTTP server (AV_AFAL_HTTP_PORT).

Environment configuration

# Core — required for both modes
AV_RELAY_URL=http://localhost:3100
AV_AGENT_ID=my-agent

# INITIATE mode — needs the peer's descriptor URL
AV_AFAL_SEED_HEX=<64-char-hex-ed25519-seed>
AV_AFAL_PEER_DESCRIPTOR_URL=http://peer:4850/descriptor

# RESPOND mode — runs an HTTP server for incoming invites
AV_AFAL_HTTP_PORT=4850
AV_AFAL_BIND_ADDRESS=127.0.0.1
AV_AFAL_TRUSTED_AGENTS='[{"agentId":"peer","publicKeyHex":"..."}]'
AV_AFAL_ALLOWED_PURPOSES=MEDIATION,COMPATIBILITY

Available tools

The MCP server exposes the following tools:

  • agentvault.get_identity — inspect the local agent identity, known peers, and pending inbox state.
  • agentvault.relay_signal — run the INITIATE/RESPOND coordination flow, including AFAL and relay session management.
  • agentvault.verify_receipt — verify a receipt signature and optionally check commitment hashes.

Minimal MCP integration

// Agent calls the MCP tool to initiate coordination
const result = await mcpClient.callTool(
  'agentvault.relay_signal',
  {
    mode: 'INITIATE',
    purpose: 'COMPATIBILITY',
    counterparty: 'agent-bob',
    my_input: 'Alice private context here',
  },
);

// The MCP server handles:
//   1. Building the contract
//   2. Creating the relay session
//   3. Sending the invite to the peer
//   4. Polling until completion
//   5. Returning structured tool output with state,
//      and the bounded signal + receipt when completed

When to use client vs MCP server

The client library is the right choice when you need to construct custom contracts, control polling intervals, handle session tokens directly, or integrate with a non-MCP agent framework. It is a thin HTTP wrapper with no opinions about agent architecture.

The MCP server is the right choice when your agent already uses MCP, you want the full INITIATE/RESPOND lifecycle managed for you, or you need AFAL direct transport (agent-to-agent without an orchestrator). The MCP server builds on the client library internally.

Relay requirements

Both integration paths require a running AgentVault relay. The relay is a Rust binary (agentvault-relay) that needs a configured provider API key. See the environment docs for the supported provider variables. For development: 

# Start the relay
ANTHROPIC_API_KEY=sk-... cargo run -p agentvault-relay

# Verify it's running
curl http://localhost:3100/health
# Returns: { "status": "ok", "verifying_key_hex": "..." }

The verifying_key_hex from the health endpoint is the Ed25519 public key needed for receipt verification. For production, set AV_SIGNING_KEY_HEX to a persistent key so receipts remain verifiable across relay restarts.

Explore the implementation