Vouch MCP Integration Guide

This guide explains how to connect AI assistants — Claude Desktop, Claude Code, Claude.ai, the Anthropic Claude API, and ChatGPT — to your Vouch workspace using the Model Context Protocol (MCP). It covers authentication, every supported client, every skill we expose, and the workflow recipes operators use most.

If you only want the short skill catalog, see docs/MCP_SKILLS.md. If you want the underlying OAuth 2.1 mechanics, see docs/OAUTH.md. This document is the operator-facing setup guide that ties everything together.

Contents

1. What MCP is, in one paragraph
2. Architecture and endpoints
3. Authentication: API keys vs OAuth
4. Skill catalog with examples
5. Connecting Claude Desktop (local, stdio)
6. Connecting Claude Code
7. Connecting Claude.ai (web)
8. Connecting the Anthropic Claude API
9. Connecting ChatGPT
10. Workflow recipes
11. Permissions, audit logs, and tenant isolation
12. Rate limits and quotas
13. Troubleshooting
14. Where to ask for help

1. What MCP is, in one paragraph

The Model Context Protocol (MCP) is an open standard from Anthropic for connecting AI assistants to external tools and data, published in late 2024. An MCP server exposes a set of tools (read or write operations) and resources (browsable data) over a transport (stdio or HTTP). MCP-aware clients — Claude Desktop, Claude Code, Claude.ai, the Anthropic SDK — discover those tools automatically and let the model call them when relevant. Vouch's MCP server exposes your workspace data as tools so an AI assistant can answer "what reviews need a response this week?", "draft a reply to this 2-star review", or "what's our Vouch Score trend across locations?" without you copy-pasting anything into a chat.

2. Architecture and endpoints

Vouch runs the MCP server as a dedicated service (services/mcp-server) alongside the main API. It connects to the same Postgres tenant database and the same agent runtime, but exposes a different surface:

All MCP traffic is rate-limited per tenant, scoped to the calling workspace, recorded in the audit log alongside the rest of your tenancy, and uses the same tenant-isolation guarantees as the REST API.

The session model is stateful: an initial Initialize request establishes a session that's identified by a Mcp-Session-Id header on subsequent requests. Auth headers are required only on the initialize.

3. Authentication: API keys vs OAuth

Vouch supports two auth modes on the MCP endpoint. Pick by use case.

3.1 Bearer API key (recommended for trusted, server-side, and your own desktop clients)

API keys are long-lived tokens minted in the Vouch admin console (Settings → API keys) or via POST /v1/api-keys. They authenticate as a tenant — not as a specific user — and they carry the scopes the issuing admin selected.

Authorization: Bearer vouch_live_abcdefg…

When to use:

• Claude Desktop and Claude Code on machines you control.
• Server-side code calling the Claude API with MCP attached.
• CI pipelines and automation.

Important: the raw key is shown once at creation. Store it in a password manager or in your client's secret store immediately. If lost, revoke and re-mint.

3.2 OAuth 2.1 access token (recommended for third-party apps and Claude.ai web)

For apps acting on behalf of a tenant user (Claude.ai's remote MCP, a third-party SaaS that integrates Vouch), use OAuth 2.1 with PKCE. The flow is documented in docs/OAUTH.md. At a glance:

1. Your app calls GET https://api.tryvouch.io/oauth/authorize?client_id=…&redirect_uri=…&response_type=code&code_challenge=…&code_challenge_method=S256&scope=….
2. The Vouch user signs in (or is already signed in) and clicks Approve.
3. Your app receives an authorization code at the redirect URI.
4. Your app exchanges the code for an access token at POST /oauth/token.
5. Use the token as Authorization: Bearer vouch_oauth_… on subsequent MCP requests.

Access tokens are 1-hour bearer tokens; refresh tokens last 30 days. The user can revoke at any time from Settings → Connected apps.

3.3 What scopes to request

Scopes determine what skills the token can call. Vouch's MCP server checks scopes per-skill.

For read-only AI assistants (the most common case), request:

read:reviews read:feedback read:surveys read:campaigns read:locations read:score read:recommendations read:approvals

4. Skill catalog with examples

Every skill is multi-tenant scoped — the handler always filters by the calling tenant. You cannot read another tenant's data through any skill.

4.1 Inbox — inbox.*

Example prompt to Claude: "Show me the 10 newest unread reviews across all locations, sorted by rating ascending."

4.2 Surveys — survey.*

Example prompt: "What's the NPS for survey survey_abc123, and what are the top 5 themes from negative responses in the last 30 days?"

4.3 Approvals — approval.*

Example prompt: "List all pending review-response drafts assigned to me, and summarize which ones look ready to publish vs which need rework."

4.4 Recommendations — recommendation.*

Example prompt: "Show me low-risk AI recommendations that haven't been applied yet, ranked by confidence."

4.5 Vouch Score — score.*

Example prompt: "What's our Vouch Score for the Dallas location, and which component is hurting us most?"

4.6 Competitors — competitor.*

Example prompt: "How do we compare to our top 3 competitors near the Dallas location on rating and review count?"

4.7 Reviews — review.*

Example prompt: "Summarize Google reviews from the last 7 days at all locations and group them by rating."

4.8 Campaigns — campaign.*

Example prompt: "Which campaign at the Dallas location has the highest response rate this month, and which has the lowest?"

4.9 Contacts — contact.*

Example prompt: "Find the contact for alice@example.com and tell me their consent state on each channel."

4.10 Locations — location.*

Example prompt: "List all active locations grouped by state."

4.11 Agent wrappers — agent.*

Thin wrappers over services/agent-runtime. These dispatch into the agent runtime via context.invokeAgent(agentId, action, input) and return the agent's structured output.

Example prompt: "Use the agent.campaign-strategist to plan a 4-week SMS-led review-request campaign for the Dallas location, targeting customers who visited in the last 30 days."

5. Connecting Claude Desktop (local, stdio)

Use this for your own machine — power-user analysts, support engineers, GMs who want a conversational view of their workspace.

5.1 One-time install

# Clone or pull the Vouch monorepo. Assumes Node 20+ and pnpm.
git clone https://github.com/your-org/vouch.git
cd vouch
pnpm install
pnpm --filter @vouch/mcp-server build

5.2 Mint an API key

1. Open the Vouch admin console → Settings → API keys.
2. Click New API key, name it (e.g. Claude Desktop — my-laptop).
3. Copy the key value. It is shown once. Store it in your password manager.

5.3 Configure Claude Desktop

Edit the Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vouch": {
      "command": "node",
      "args": ["/absolute/path/to/vouch/services/mcp-server/dist/server.js", "stdio"],
      "env": {
        "VOUCH_API_KEY": "vouch_live_…",
        "DATABASE_URL": "postgresql://…",
        "AGENT_RUNTIME_URL": "https://vouch-agent-runtime.internal..."
      }
    }
  }
}

The stdio transport runs the MCP server in-process and authenticates via the API key. Restart Claude Desktop. You should see Vouch tools in the tools picker.

5.4 Self-hosted vs. SaaS

If you're a Vouch SaaS customer (most readers), you usually don't run the stdio variant — the Claude Desktop UI now supports remote MCP servers via mcpServers[name].url, which is simpler:

{
  "mcpServers": {
    "vouch": {
      "url": "https://api.tryvouch.io/mcp",
      "headers": {
        "Authorization": "Bearer vouch_live_…"
      }
    }
  }
}

That's the recommended config for most users. Restart Claude Desktop after editing.

6. Connecting Claude Code

Claude Code (CLI / IDE extension) supports MCP via:

claude mcp add vouch --url https://api.tryvouch.io/mcp \
  --header "Authorization: Bearer vouch_live_…"

Or by editing ~/.config/claude-code/mcp_servers.json:

{
  "mcpServers": {
    "vouch": {
      "url": "https://api.tryvouch.io/mcp",
      "headers": {
        "Authorization": "Bearer vouch_live_…"
      }
    }
  }
}

In a Claude Code session, type /mcp to confirm Vouch is connected. Tools appear under the vouch namespace (e.g. mcp__vouch__inbox.list).

7. Connecting Claude.ai (web)

Anthropic added remote MCP support to Claude.ai for Pro, Team, and Enterprise plans. The flow uses OAuth so you never paste an API key into a browser.

7.1 First-time setup (one user)

1. In Claude.ai, open Settings → Connectors.
2. Click Add custom connector.
3. Enter:
   • Name: Vouch
   • MCP server URL: https://api.tryvouch.io/mcp
4. Click Connect. Claude.ai will redirect you to Vouch's OAuth consent screen.
5. Sign in with your Vouch account (Microsoft Entra ID / SAML / email).
6. Review the scopes requested and click Approve.
7. You're returned to Claude.ai with Vouch connected.

The connection is per-user. Each user in your workspace who wants Vouch in Claude.ai goes through this once.

7.2 Team-wide setup (Enterprise)

Enterprise admins can pre-register Vouch as a workspace-wide connector so users don't each need to manually add it. The admin pastes the same MCP server URL and ticks Available to all workspace members. Users still complete the OAuth handshake on first use (one-click).

7.3 What it looks like in a chat

Once connected, Claude can call Vouch tools when relevant. You don't have to mention them by name. Try:

"What's the rating trend across our 12 locations in the last 30 days, and which one had the biggest drop?"

Claude calls location.list → review.summary per location → and synthesizes a written answer with a small table. Each tool call shows up in the chat as an expandable card so you can see exactly what was queried.

8. Connecting the Anthropic Claude API

Build your own agent on top of Claude that uses Vouch as its tool surface. The Messages API accepts an mcp_servers parameter (Anthropic SDK 0.40+) that attaches one or more MCP servers and lets Claude call their tools.

8.1 Node / TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  mcp_servers: [
    {
      type: "url",
      url: "https://api.tryvouch.io/mcp",
      name: "vouch",
      authorization_token: process.env.VOUCH_API_KEY,
    },
  ],
  messages: [
    {
      role: "user",
      content:
        "Find the 5 most recent 1-star reviews across our network and draft an apology reply for each one. Don't post — return drafts for me to review.",
    },
  ],
});

Claude will issue tool calls to inbox.list (filter rating=1), inbox.get for each, and agent.compliance-critic on each draft before returning the assembled response.

8.2 Python

from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://api.tryvouch.io/mcp",
            "name": "vouch",
            "authorization_token": os.environ["VOUCH_API_KEY"],
        }
    ],
    messages=[{"role": "user", "content": "Summarize this week's NPS by location."}],
)

8.3 Tool-call observability

The response includes a content array with one or more mcp_tool_use and mcp_tool_result blocks describing every Vouch tool call made during the turn. Log these for auditing or to display in your own UI.

8.4 Streaming

mcp_servers works with streaming too — use client.messages.stream(...) instead. Tool-call events arrive as they happen.

9. Connecting ChatGPT

ChatGPT's native MCP support is rolling out for Enterprise and team customers in 2026; for most other plans the established path is Custom GPT Actions, which use OpenAPI rather than MCP. Both paths are documented below.

9.1 The MCP path (ChatGPT Enterprise / Team where available)

1. In ChatGPT, open Settings → Connectors → Add custom connector.
2. Enter https://api.tryvouch.io/mcp as the server URL.
3. Choose OAuth authentication. ChatGPT will redirect to Vouch's OAuth consent screen.
4. Sign in, review scopes, and approve. ChatGPT returns to the chat with Vouch tools available.

Behaviour is functionally identical to Claude.ai's MCP support: ChatGPT will call Vouch skills when relevant during a conversation.

If your ChatGPT tenant doesn't have MCP connectors in the settings, you're on a plan that hasn't received the rollout yet. Use the Custom GPT Actions path below.

9.2 The OpenAPI Actions path (Custom GPT, ChatGPT Plus / Pro / Team)

Custom GPTs in ChatGPT use Actions, which are OpenAPI-described REST endpoints, not MCP. The good news: Vouch's MCP skills also exist as REST endpoints on the main API and we publish a complete OpenAPI spec at https://api.tryvouch.io/docs/openapi.json. You can wrap that spec in a Custom GPT in five minutes.

Step 1 — Mint an API key

Same as the Claude Desktop flow above: Settings → API keys → New API key, copy once.

Step 2 — Create a Custom GPT

1. In ChatGPT, click your name → My GPTs → Create a GPT.
2. In the Configure tab, give it a name (e.g. Vouch Operator), a description, and instructions.

Step 3 — Add the Action

1. Scroll to Actions → Create new action.

2. Click Import from URL and paste:

   https://api.tryvouch.io/docs/openapi.json
   

3. ChatGPT will import every Vouch REST endpoint. Trim to the subset you want exposed (recommended: reviews, inbox, campaigns, surveys, locations, score, recommendations). Bulk-disable the others.

4. Under Authentication, choose API Key with Custom header name Authorization and value Bearer <paste-your-vouch-api-key>. Also add a custom header x-tenant-id: <your-tenant-id>.

5. Save the Action.

Step 4 — Add instructions

In the Configure tab → Instructions, paste something like:

You are a Vouch reputation operator assistant. Use the Vouch API actions to:
- Find unresponded reviews
- Summarize sentiment by location
- Draft replies for human review (never auto-post)
- Surface the Vouch Score per location

Always cite the location and the source platform when reporting a review.
Always defer to a human before publishing a reply.

Step 5 — Test

Open the Preview pane on the right and ask: "Show me unresponded 1-star Google reviews from the last 7 days, by location." The GPT will call the Vouch API and respond.

Step 6 — Publish

When you're happy, click Update in the top right and choose visibility (Only me / Anyone with link / GPT Store). For team-only access, Only me + share the link inside your org is the safest default.

Note: Custom GPT Actions cannot use OAuth 2.1 PKCE today — they only support static API key, OAuth 2.0 client-credentials, or OAuth 2.0 authorization-code with a static client secret. Use a Vouch API key bound to a service account with the minimum scopes you need.

10. Workflow recipes

A handful of high-leverage things to ask whichever AI assistant you've connected:

10.1 The weekly inbox triage

"List unresponded reviews from the last 7 days across all locations. Group by location, sort by rating ascending. For each one, draft a personalized reply in our brand voice. Return drafts only — don't post anything."

Skills used: location.list, inbox.list (per location, status=new), agent.template-generator for each draft.

10.2 The monthly reputation summary

"Generate a monthly reputation summary for last month: total new reviews per location, average rating, response rate, Vouch Score trend, and the top 3 themes from open-text feedback. Format as markdown I can paste into a board update."

Skills used: review.summary, score.location per location, survey.stats, agent.reputation-insight.

10.3 The NPS detractor sweep

"Find every NPS detractor (0–6) from the last 14 days, show me their comment, and group them by theme. Highlight any that mention a specific staff member by name."

Skills used: survey.list, survey.responses (filter by NPS bucket), agent.outcome-analyst.

10.4 The compliance pre-check

"Here's a draft SMS for our review-request campaign: 'Hi {{first_name}}, please review us on Google: {{link}}'. Run the compliance critic on it and tell me what to fix."

Skills used: agent.compliance-critic. Output cites the specific TCPA / CTIA / FTC requirements the draft fails or passes.

10.5 The location vs. competitor sweep

"For our Dallas location, compare our last-30-day average rating and review velocity to our top 3 tracked competitors. Where are we losing and what should we focus on?"

Skills used: review.summary, competitor.list, score.location, agent.reputation-insight.

10.6 The campaign post-mortem

"How did campaign cmp_abc123 perform vs the previous version? Show send / open / click / response rates, sentiment of the resulting reviews, and what the outcome-analyst thinks the next variation should be."

Skills used: campaign.get, campaign.metrics, agent.outcome-analyst, agent.experiment-designer.

11. Permissions, audit logs, and tenant isolation

Tenant isolation

Every skill handler resolves context.tenantId from the auth token and filters every database query by it. There is no way for an API key issued by Tenant A to read data from Tenant B; the constraint is enforced at the application layer and verified by the database indexes.

Scopes

The OAuth 2.1 path enforces scopes per skill — a token with only read:reviews cannot call contact.suppress even if it tries. The API-key path inherits the scope set the issuing admin selected when minting the key (default: read-only across all areas).

Audit logs

Every MCP tool call is recorded in the workspace's audit log with:

• Caller identity (API key ID or OAuth client ID + user ID)
• Tool name (e.g. inbox.list)
• Input shape (without secret values)
• Result count / outcome
• Timestamp, IP, user agent

Admins can view the audit log in Settings → Audit log and export it as CSV.

Write skills

Today only a small set of skills are write-capable (contact.suppress, agent-triggered actions where you've opted in). All write skills are scope-gated, audit-logged, and — for compliance-sensitive writes — pass through agent.compliance-critic before executing.

Revoking access

12. Rate limits and quotas

429 responses include a Retry-After header. The audit log records throttled calls.

If you need higher limits, contact support@aartha.ai.

13. Troubleshooting

"Authentication required" / 401

• Confirm the Authorization: Bearer … header is present on the initialize request.
• Check the API key hasn't been revoked: Settings → API keys.
• Check the OAuth token hasn't expired: tokens last 1 hour; refresh with the refresh token.

Tool calls return empty arrays

• Re-confirm the calling tenant has data in that table. Run the equivalent REST endpoint to verify.
• Confirm the scope on the token includes the read scope for that area.

Claude Desktop / Claude Code doesn't see the tools

• Restart the client. MCP discovery happens on session start.
• Check ~/Library/Logs/Claude/mcp*.log (macOS) or the equivalent on Windows for transport errors.
• For stdio: confirm the node binary path is absolute and the server bundle exists at the expected location.

Tool calls hang or timeout

• The MCP server's default per-call timeout is 60 seconds. Long-running agent.* calls may approach this — split into smaller calls or use background workflows in the agent runtime instead.

"ChunkLoadError" or hydration error in browser-connected clients

• This is a stale client-side bundle. Refresh the page. See the marketing site's ChunkErrorReloader for the auto-recovery pattern.

My ChatGPT Custom GPT can't call Vouch

• Confirm both Authorization: Bearer … and x-tenant-id: … are set in the action's auth config.
• Confirm the OpenAPI spec imported all the way (large specs sometimes truncate — use ChatGPT's "Validate" button).
• Confirm the GPT is using Send as a single request (not "split per operation") for endpoints that need pagination.

14. Where to ask for help

For developer reference materials, see:

• Skill catalog — short reference of every skill
• OAuth 2.1 mechanics — full reference for the authorization server
• API Reference (Swagger UI) — interactive REST endpoints for the same data
• User Guide — non-developer onboarding for Vouch itself