MCP 服务器

FoxTrove Voice MCP Server

Public read-only MCP server for FoxTrove Voice, enabling LLMs to query call logs, customer records, assistant stats, and analytics via secure OAuth.

README

FoxTrove Voice MCP Server

Public, read-only Model Context Protocol server for FoxTrove Voice. 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:

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

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

{
  "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) 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

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: