# @verifiedstate/mcp

Official MCP bridge for **[VerifiedState](https://verifiedstate.ai)** — 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](https://verifiedstate.ai) · [API keys](https://verifiedstate.ai/keys) |

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

```http
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

```bash
npm install @verifiedstate/mcp
```

Or use without installing:

```bash
npx -y @verifiedstate/mcp
```

## Environment

| Variable | Required | Description |
|----------|----------|-------------|
| `VERIFIEDSTATE_API_KEY` | Yes (for `tools/call`) | API key from [verifiedstate.ai/keys](https://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:

```json
{
  "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:

```json
{
  "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):

```json
{
  "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

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

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

## License

MIT — see [LICENSE](./LICENSE).

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).