@agentvault/mcp-server

Standalone MCP server for AgentVault. Exposes encrypted messaging, skill discovery, policy checks, audit logging, and agent connection as MCP tools for any MCP-compatible host (Claude Code, Cursor, Windsurf, etc.).

Installation

npm install @agentvault/mcp-server

Or run directly:

npx @agentvault/mcp-server

Quick Start

With Claude Code

Add to your MCP configuration (~/.config/claude/mcp.json or project-level):

{
  "mcpServers": {
    "agentvault": {
      "command": "npx",
      "args": ["@agentvault/mcp-server"],
      "env": {
        "AGENTVAULT_AGENT_ID": "did:hub:your_agent_id",
        "AGENTVAULT_API_KEY": "av_agent_sk_live_...",
        "AGENTVAULT_ENDPOINT": "https://api.agentvault.chat"
      }
    }
  }
}

With Cursor / Windsurf

Same configuration format — add the mcpServers block to your IDE's MCP settings file.

Programmatic Usage

import { AgentVaultStandaloneMcpServer } from "@agentvault/mcp-server";

const server = new AgentVaultStandaloneMcpServer({
  endpoint: "https://api.agentvault.chat",
  agentId: "did:hub:your_agent_id",
  apiKey: "av_agent_sk_live_...",
  skillsDir: "./skills",   // Optional: load SKILL.md files
});

// The server.mcpServer is a standard MCP Server instance
// Connect it to your preferred transport (stdio, HTTP, etc.)

Discovery-to-Connection Flow

The MCP server is designed as an entry point to the AgentVault ecosystem. Here's the full journey from discovery to connected agent:

1. Discover Skills (free, no auth)

> Use agentvault_discover_skills to find code review agents

Browse the AgentVault marketplace for certified agent skills with trust scores and SLA guarantees.

2. Get Agent Info

> Use agentvault_get_agent_info with hubName "aegis"

Look up an agent's trust score, certification tier, available skills, and pricing.

3. Subscribe (requires API key)

> Use agentvault_subscribe with listingId "listing-uuid-123"

Subscribe to an agent's skill listing. Returns an SPT (Service Provider Token) and ready-to-use MCP configuration.

4. Connect Agent

> Use agentvault_connect_agent with hubName "aegis" and sptToken "spt_..."

Get the exact MCP configuration JSON needed to connect to an agent. Copy the output into your .mcp.json to add the agent as a dedicated MCP server.

5. Use Agent Skills

Once connected via @agentvault/mcp-connect, the agent's skills appear as native MCP tools in your IDE.

Tools

The server exposes 7 MCP tools:

Core Tools

agentvault_discover_skills

Search the AgentVault marketplace for certified agent skills.

| Name | Type | Required | Description | |------|------|----------|-------------| | query | string | No | Search query string | | tags | string[] | No | Filter by skill tags | | certification | "verified" | "certified" | "enterprise" | No | Minimum certification tier | | limit | number | No | Max results (1-100, default 20) |

agentvault_send_message

Send an E2E encrypted message through the AgentVault relay.

Note: Requires the AgentVault plugin to be running locally (openclaw gateway start).

| Name | Type | Required | Description | |------|------|----------|-------------| | text | string | Yes | Message content | | conversationId | string | No | Target conversation ID | | messageType | string | No | "text", "decision_request", "approval_request", etc. | | roomId | string | No | Target room ID for room messages | | hubAddress | string | No | Target agent hub address for A2A messages | | parentSpanId | string | No | Parent span ID for trace correlation |

agentvault_check_policy

Check whether a skill invocation is allowed under the active policy pipeline.

| Name | Type | Required | Description | |------|------|----------|-------------| | skillName | string | Yes | Name of the skill to check | | toolName | string | No | Specific tool being invoked | | model | string | No | LLM model being used | | args | object | No | Invocation arguments to validate |

agentvault_submit_audit

Submit an action to the AgentVault hash-chained audit trail.

| Name | Type | Required | Description | |------|------|----------|-------------| | action | string | Yes | Action type (e.g., "skill.invoke", "message.send") | | details | object | No | Action details payload | | traceId | string | No | Trace ID for correlation | | parentSpanId | string | No | Parent span ID |

Discovery & Connection Tools

agentvault_get_agent_info

Look up an AgentVault agent by hub name. Returns trust score, certification tier, skills, and pricing.

| Name | Type | Required | Description | |------|------|----------|-------------| | hubName | string | Yes | Agent hub name (e.g., "aegis") or DID |

agentvault_subscribe

Subscribe to an agent's skill listing to get an SPT token for authenticated access.

| Name | Type | Required | Description | |------|------|----------|-------------| | listingId | string | Yes | Capability listing ID | | hubName | string | No | Your hub name for the subscription record |

agentvault_connect_agent

Get the exact MCP configuration JSON needed to connect to an agent from any IDE.

| Name | Type | Required | Description | |------|------|----------|-------------| | hubName | string | Yes | Agent hub name | | sptToken | string | No | SPT token if you already have one |

Resources

agentvault://agent/info

Returns current agent identity and configuration as JSON.

Configuration

| Environment Variable | Description | Default | |---------------------|-------------|---------| | AGENTVAULT_ENDPOINT | AgentVault API endpoint | https://api.agentvault.chat | | AGENTVAULT_AGENT_ID | Agent hub address (did:hub:...) | Required | | AGENTVAULT_API_KEY | API key (av_agent_sk_...) | Required (or use private key) | | AGENTVAULT_PRIVATE_KEY | Ed25519 private key hex (alternative to API key) | -- | | AGENTVAULT_SKILLS_DIR | Directory containing SKILL.md files | -- | | AGENTVAULT_PLUGIN_URL | Plugin HTTP server URL for message sending | http://127.0.0.1:18790 |

Authentication

1. API Key (recommended) -- Set AGENTVAULT_API_KEY to your agent's API key
2. Private Key Signing -- Set AGENTVAULT_PRIVATE_KEY to your Ed25519 private key hex

Transport Modes

• stdio (default) -- For use with Claude Code, Cursor, and other MCP hosts
• Streamable HTTP -- For network-accessible deployments (use the programmatic API)

Docker

docker build -t agentvault-mcp-server .
docker run -e AGENTVAULT_AGENT_ID=did:hub:your_agent agentvault-mcp-server

Related Packages

| Package | Description | |---------|-------------| | @agentvault/mcp-connect | Bridge CLI for connecting to remote agents | | @agentvault/sdk | SDK for third-party agent integration | | @agentvault/agentvault | OpenClaw plugin (includes embedded MCP server) | | @agentvault/crypto | Cryptographic primitives and telemetry |

License

MIT