# FoxTrove Voice MCP Server

Public, read-only [Model Context Protocol](https://modelcontextprotocol.io) server for [FoxTrove Voice](https://voice.foxtrove.ai). Hosted at **`https://mcp.voice.foxtrove.ai/mcp`**.

Connect any MCP-capable LLM client — Claude Desktop, Cursor, ChatGPT, Zed, custom agents — to a FoxTrove Voice tenant and ask real questions: "what calls came in today?", "any calls about warranty issues this week?", "who asked about pricing?", "how is the booking assistant performing vs last week?". The LLM picks the right tool, the server enforces per-tenant OAuth, and the answers come back as structured JSON.

This repository is the *public* proxy layer only. It verifies OAuth bearer JWTs against the main FoxTrove app's JWKS, then forwards tool calls to the main app's internal HTTP API. It has no database credentials, no schema knowledge, and no tenant logic of its own — the main app (private repo) is the source of truth. That split keeps this codebase safe to open-source and submit to MCP marketplaces.

---

## Tools

All tools are read-only and scoped to the authenticated tenant.

### Calls
- **`list_calls`** — browse recent calls with filters (since/until, assistant, outcome).
- **`get_call`** — one call in full; opt in to transcript and recording URL.
- **`search_calls`** — semantic search across call transcripts and summaries.

### Customers
- **`get_customer_context`** — unified cross-CRM snapshot for one customer by phone / email / id.
- **`search_customers`** — find customers by name / phone / email fragment.

### Assistants
- **`list_assistants`** — voice assistants configured on the tenant.
- **`get_assistant_stats`** — aggregate performance metrics for one assistant.

### Follow-ups & appointments
- **`list_followups`** — open action items flagged during calls.
- **`list_appointments`** — bookings made during voice calls.

### Analytics
- **`get_call_metrics`** — counts and durations, groupable by day / week / month / assistant / outcome.
- **`get_outcome_breakdown`** — distribution of outcomes ("qualified rate this month").
- **`get_topic_trends`** — top topics / objections across calls.
- **`compare_periods`** — period-over-period deltas (calls, qualified, avg duration, booked).

---

## Install

### Claude Desktop

Open **Settings → Developer → Edit Config** and add:

```json
{
  "mcpServers": {
    "foxtrove-voice": {
      "url": "https://mcp.voice.foxtrove.ai/mcp"
    }
  }
}
```

Restart Claude Desktop. The first tool call will open a browser window to sign in with FoxTrove; approve access and you're done.

### Cursor

Open **Settings → MCP → Add new MCP Server**, paste `https://mcp.voice.foxtrove.ai/mcp`, and save. Or edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "foxtrove-voice": {
      "url": "https://mcp.voice.foxtrove.ai/mcp"
    }
  }
}
```

### ChatGPT (web)

**Settings → Connectors → Add MCP server** → `https://mcp.voice.foxtrove.ai/mcp`.

### Zed

Add to your Zed settings:

```json
{
  "context_servers": {
    "foxtrove-voice": {
      "source": "custom",
      "url": "https://mcp.voice.foxtrove.ai/mcp"
    }
  }
}
```

### Custom client (Streamable HTTP)

Any client that speaks MCP Streamable HTTP with OAuth 2.1 works. Server endpoint:

```
https://mcp.voice.foxtrove.ai/mcp
```

Authorization server discovery:

```
https://voice.foxtrove.ai/.well-known/oauth-authorization-server
```

PKCE is required. Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) is supported at `POST https://voice.foxtrove.ai/oauth/register`.

---

## Scopes

| Scope | Grants access to |
|---|---|
| `read:calls` | `list_calls`, `get_call`, `search_calls` |
| `read:customers` | `get_customer_context`, `search_customers` |
| `read:assistants` | `list_assistants`, `get_assistant_stats` |
| `read:followups` | `list_followups` |
| `read:appointments` | `list_appointments` |
| `read:analytics` | `get_call_metrics`, `get_outcome_breakdown`, `get_topic_trends`, `compare_periods` |
| `read:all` | Convenience scope covering all of the above (default for v1 installs) |

Write scopes are reserved but not issued in v1 — this server is read-only by design.

---

## OAuth flow

```
LLM client ──(1) discover───▶  voice.foxtrove.ai/.well-known/oauth-authorization-server
           ──(2) register──▶  voice.foxtrove.ai/oauth/register    (dynamic client registration)
           ──(3) authorize─▶  voice.foxtrove.ai/oauth/authorize   (user consents in browser)
           ──(4) token─────▶  voice.foxtrove.ai/oauth/token       (PKCE code → access + refresh)
           ──(5) call tool─▶  mcp.voice.foxtrove.ai/mcp           (Bearer JWT; 1h lifetime)
                                      │
                                      ├─ verify JWT vs voice.foxtrove.ai/.well-known/jwks.json
                                      │
                                      └─ proxy to voice.foxtrove.ai/api/internal/mcp/<tool>
```

Access tokens are RS256-signed JWTs with a 1-hour lifetime. Refresh tokens rotate on every use and can be revoked per-client from the FoxTrove settings UI (**Connected apps**).

---

## Development

```bash
git clone https://github.com/foxtrove-ai/foxtrove-voice-mcp
cd foxtrove-voice-mcp
npm install
cp .env.example .env.local
npm run dev
```

The server runs on `http://localhost:3000`; the MCP endpoint is `http://localhost:3000/mcp`. Point any MCP client at that URL while developing.

Default env values (see `.env.example`) point at production `voice.foxtrove.ai`. Override `MCP_INTERNAL_API_BASE`, `MCP_ISSUER`, and `MCP_JWKS_URI` to test against a staging instance.

---

## Project layout

```
app/
  mcp/route.ts         MCP Streamable HTTP endpoint
  page.tsx             Install landing page at mcp.voice.foxtrove.ai/
lib/
  mcp-server.ts        Creates the McpServer and registers all tools
  auth.ts              JWKS-based bearer JWT verification
  proxy.ts             HTTP proxy to the main app's internal MCP API
  config.ts            Env-driven config
  tools/               Per-domain tool definitions (calls, customers, ...)
```

---

## Contributing

This repo is the public user-facing MCP layer. All business logic, database access, and tenant logic live in the private `voice-ai-wrapper` repo. PRs welcome for:

- Client install snippets for new MCP-capable apps
- Tool description wording improvements (these are the product)
- Packaging / deployment / transport improvements

Please keep this repo free of anything tenant-specific or credentialed.

---

## License

MIT © 2026 FoxTrove. See [LICENSE](./LICENSE).