@verifiedstate/mcp

Official MCP bridge for VerifiedState — connect Claude Code, Cursor, Windsurf, and other MCP clients to verified memory and Proof Meter.

This package runs a local stdio MCP server that proxies tool calls to the hosted endpoint. Your API key never leaves your machine except as Authorization: Bearer to VerifiedState.

Hosted MCP server

Item	Value
MCP URL	`https://mcp.verifiedstate.ai/mcp`
Discovery (Agent Card)	`https://mcp.verifiedstate.ai/.well-known/agent-card.json`
Dashboard & keys	verifiedstate.ai · API keys

Clients that support remote HTTP MCP can point directly at the URL above and send:

Authorization: Bearer vs_live_...

Tools (13)

Tool	Description
`memory_ingest`	Ingest content into verified memory; returns `artifact_id`.
`memory_query`	Semantic search over verified memory with ranked assertions and receipts.
`memory_verify`	Run verification on an assertion; produces a signed receipt.
`memory_health`	Namespace health: counts, verification ratio, stale/expired, conflicts.
`meter_authorize`	Create a Proof Meter capability with a spend budget.
`meter_spend`	Record spend against a capability; returns a hash-chained receipt.
`meter_budget`	Remaining budget and spend summary for a capability.
`meter_settle`	Settle receipts into a Merkle-rooted batch.
`meter_verify`	Cryptographically verify a spend receipt.
`meter_receipts`	List and filter spend receipts for a namespace.
`session_save`	Persist session state (summary, files, decisions, next steps).
`session_load`	Load the last saved session for a project.
`session_end`	End session with optional summary (sessions also auto-persist).

Install

npm install @verifiedstate/mcp

Or use without installing:

npx -y @verifiedstate/mcp

Environment

Variable	Required	Description
`VERIFIEDSTATE_API_KEY`	Yes (for `tools/call`)	API key from verifiedstate.ai/keys
`VERIFIEDSTATE_NAMESPACE_ID`	No	Default `namespace_id` injected into tool arguments when omitted

MCP configuration

Cursor

Add to your MCP config (e.g. Cursor Settings → MCP), replacing the placeholder key:

{
  "mcpServers": {
    "verifiedstate": {
      "command": "npx",
      "args": ["-y", "@verifiedstate/mcp"],
      "env": {
        "VERIFIEDSTATE_API_KEY": "vs_live_YOUR_KEY_HERE",
        "VERIFIEDSTATE_NAMESPACE_ID": "optional-default-namespace-uuid"
      }
    }
  }
}

Claude Code

Same shape as Cursor — merge into your Claude Code MCP configuration:

{
  "mcpServers": {
    "verifiedstate": {
      "command": "npx",
      "args": ["-y", "@verifiedstate/mcp"],
      "env": {
        "VERIFIEDSTATE_API_KEY": "vs_live_YOUR_KEY_HERE"
      }
    }
  }
}

Windsurf

Use the equivalent MCP server entry in Windsurf’s config (stdio command + env):

{
  "mcpServers": {
    "verifiedstate": {
      "command": "npx",
      "args": ["-y", "@verifiedstate/mcp"],
      "env": {
        "VERIFIEDSTATE_API_KEY": "vs_live_YOUR_KEY_HERE"
      }
    }
  }
}

Remote HTTP (if your client supports it)

Point the client at https://mcp.verifiedstate.ai/mcp and configure Bearer authentication with your API key. The exact JSON shape depends on the product; refer to your client’s docs for “remote MCP” or “SSE/HTTP MCP”.

Programmatic config helper

import { getConfig } from '@verifiedstate/mcp';

const config = getConfig('vs_live_...', 'optional-namespace-id');
// => { mcpServers: { verifiedstate: { command, args, env } } }

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md.

verifiedstate-mcp