# Vouch MCP Server

> Connect your AI IDE (Cursor, Claude Desktop, Windsurf, Zed) to your Vouch workspace over the Model Context Protocol. Query your projects, interviews, assumptions, and segments as first-class context.

- Endpoint: `https://vouch.specky.space/api/public/mcp`
- Transport: MCP Streamable HTTP (POST only; GET/DELETE return 405)
- Auth: `Authorization: Bearer vch_…` — generate at [/settings/mcp](https://vouch.specky.space/settings/mcp)

## Why connect Vouch over MCP

Your customer interviews, ranked assumptions, and segment scores are the highest-signal context for any product decision an AI assistant can help with. Vouch's MCP server exposes them read-only so you can:

- Ground roadmap or spec drafts in real customer quotes (every excerpt is citable).
- Ask "what do we already know about X?" before scheduling another interview.
- Have the assistant cross-check a proposal against the project's open assumptions.

## Setup

1. Sign in at [vouch.specky.space](https://vouch.specky.space).
2. Open [/settings/mcp](https://vouch.specky.space/settings/mcp), click **Generate token**, copy the `vch_…` value (shown once).
3. Add the server to your IDE config.

### Cursor / Claude Desktop / Windsurf

```json
{
  "mcpServers": {
    "vouch": {
      "url": "https://vouch.specky.space/api/public/mcp",
      "headers": {
        "Authorization": "Bearer vch_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Zed

```json
{
  "context_servers": {
    "vouch": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://vouch.specky.space/api/public/mcp", "--header", "Authorization: Bearer vch_YOUR_TOKEN_HERE"]
      }
    }
  }
}
```

## Tools exposed

| Tool | Purpose |
|---|---|
| `list_projects` | List your projects with id, name, idea, target customer, and counts. |
| `get_project` | Full project — assumptions, interviews, segments, pilots, cases. |
| `search_interviews` | Keyword search across all interviews in a project. Returns citable excerpts with interviewee name, company, date. |
| `get_assumptions` | All assumptions with FeDeVi category, importance, and evidence strength. |
| `get_segments` | Candidate segments with 12-dimension scores and reasoning. |

All tools are scoped to the authenticated user — tokens never see another user's data.

## Recommended prompts

- *"Use Vouch to list my projects, then summarize what's been validated for the [name] idea."*
- *"Search interviews in project [id] for 'pricing' and quote the three strongest objections."*
- *"Read assumptions for project [id]. Which Desirable assumptions still have weak evidence?"*
- *"Get segments for project [id] and recommend which one to pursue first, citing scores."*

## Security

- Tokens are SHA-256 hashed at rest; the raw `vch_…` value is only displayed once.
- Revoke at [/settings/mcp](https://vouch.specky.space/settings/mcp). Revoked or invalid tokens return HTTP 401 with a `WWW-Authenticate` hint.
- Suspicious activity (high failure rate, multiple IPs per token, burst usage, use after revocation) is surfaced in [/settings/mcp](https://vouch.specky.space/settings/mcp) and the admin console.
- Read-only: the MCP server cannot create, edit, or delete projects, interviews, or assumptions.

## Error reference

| HTTP | Meaning | Fix |
|---|---|---|
| 401 `missing` | No `Authorization` header. | Add `Authorization: Bearer vch_…`. |
| 401 `invalid_token` | Token not recognized. | Generate a new one at /settings/mcp. |
| 401 `token_revoked` | Token was revoked. | Generate a new one and update IDE config. |
| 405 | GET/DELETE attempted. | MCP Streamable HTTP uses POST. |
| 406 (from your IDE/proxy) | Client missing `Accept: application/json, text/event-stream`. | Use a real MCP client; do not hand-roll fetch without that header. |

## Spec & implementation

- MCP Streamable HTTP spec: <https://modelcontextprotocol.io/specification/2025-06-18/basic/transports>
- Built with [mcp-tanstack-start](https://github.com/codyde/mcp-tanstack-start)
- See [/llms.txt](https://vouch.specky.space/llms.txt) and [/agents.md](https://vouch.specky.space/agents.md) for the broader product context AI agents should read first.