@agentvault/mcp-server

@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

• API Key (recommended) -- Set AGENTVAULT_API_KEY to your agent's API key
• 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