> ## Documentation Index
> Fetch the complete documentation index at: https://f4c7a9e2d8b1-docs.tenzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, Cursor, and other MCP clients to Tenzo to query your jobs, candidates, applications, calls, and templates and submit assistant feedback

<Info>
  **Available to all organizations** — Tenzo hosts a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the read endpoints of the [Tenzo Public API](https://api.tenzo.ai/v1/tenzo-api-documentation) as tools that any MCP-compatible AI client can call, plus a `submit_feedback` write tool the assistant uses to log questions it struggled with (internal feedback only).
</Info>

## Overview

Tenzo's MCP server lets you point an MCP-compatible client (Claude.ai, Claude Desktop, Claude Code, Cursor, Windsurf, etc.) at your Tenzo workspace and ask natural-language questions like *"summarize the last 20 calls for job X"* or *"list applications stuck in screening for more than a week."* The model can call Tenzo tools directly to fetch the data it needs.

There are two ways to connect, depending on the client:

* **OAuth connector** — for hosted clients like Claude.ai that support the [MCP HTTP transport with OAuth 2.1](https://modelcontextprotocol.io/specification). Sign in with your Tenzo account; no API key required.
* **`.mcp.json` configuration** — for local clients (Claude Code, Cursor, Windsurf, Claude Desktop). Authenticated with a Tenzo API key.

The server is **read-only for your recruiting data**: the tools that proxy the Public API only expose `GET` endpoints. Write operations on recruiting data (creating jobs, upserting applications, posting comments) are not available through MCP — use the [Public API](https://api.tenzo.ai/v1/tenzo-api-documentation) directly for those. The one exception is `submit_feedback`, which lets the assistant record questions it struggled with so we can improve it; it writes only to an internal feedback log and exposes no recruiting data.

## Option 1 — OAuth connector (Claude.ai and other hosted clients)

For Claude.ai, add Tenzo as a custom connector. The first time you use it, you'll be redirected to Tenzo to sign in and approve access.

<Steps>
  <Step title="Open the connectors page in Claude">
    In Claude.ai, go to **Settings** → **Connectors** → **Add custom connector**.
  </Step>

  <Step title="Provide the connector URL">
    Enter the Tenzo MCP server URL:

    ```
    https://api.tenzo.ai/mcp
    ```

    Leave the authentication type as the default (OAuth). Claude will discover Tenzo's authorization server automatically.
  </Step>

  <Step title="Approve access">
    Claude opens Tenzo's sign-in page in a popup. Log in with your normal Tenzo account, then click **Approve** on the consent screen.

    The connector now appears in Claude's tools list and is ready to use.
  </Step>
</Steps>

<Tip>
  Access is scoped to your Tenzo organization and the permissions on your account. The connector cannot see data from other organizations.
</Tip>

### Revoking access

Tenzo issues short-lived access tokens only — no refresh tokens. Once the access token expires, the client has to send the user back through the OAuth flow to get a new one. To stop a connector from talking to Tenzo, remove it from the client (e.g. **Settings → Connectors** in Claude.ai); any in-flight token will stop working when it expires, and the client cannot mint a new one without going through consent again.

## Option 2 — `.mcp.json` (Claude Code, Cursor, Windsurf, Claude Desktop)

Local clients read MCP server definitions from a `.mcp.json` (or equivalent) config file. Add the following entry:

```json theme={null}
{
  "mcpServers": {
    "tenzo": {
      "type": "http",
      "url": "https://api.tenzo.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${TENZO_API_KEY}"
      }
    }
  }
}
```

<Steps>
  <Step title="Generate a Tenzo API key">
    Follow [Generating an API Key](/settings/api-webhook-config#generating-an-api-key) to create a key in **Settings → Developer Tools**. Your key starts with `tenzo_pk_`.
  </Step>

  <Step title="Export the key">
    Export it as an environment variable so it stays out of your config file:

    ```sh theme={null}
    export TENZO_API_KEY=tenzo_pk_...
    ```
  </Step>

  <Step title="Add the entry to your client config">
    * **Claude Code** — add to `.mcp.json` at the root of your project (or your global Claude Code config)
    * **Cursor** — `~/.cursor/mcp.json`
    * **Windsurf** — `~/.codeium/windsurf/mcp_config.json`
    * **Claude Desktop** — `claude_desktop_config.json` (see [Anthropic's docs](https://modelcontextprotocol.io/quickstart/user) for the platform-specific path)
  </Step>

  <Step title="Restart the client">
    Restart your MCP client. The Tenzo tools should appear in the client's tool picker.
  </Step>
</Steps>

<Warning>
  Treat your API key like a password. Anyone with the key has the same read access to your organization's Tenzo data as you do. Revoke compromised keys from **Settings → Developer Tools → API Keys**.
</Warning>

## Available tools

Every tool maps 1:1 to a `GET` endpoint in the [Tenzo Public API](https://api.tenzo.ai/v1/tenzo-api-documentation). Click any tag link below to see the full request and response schemas for the underlying endpoint.

### Analytics

| Tool                         | Description                                            | Public API                                                                 |
| ---------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- |
| `get_analytics_metrics`      | Analytics metrics and chart payloads for the dashboard | [Analytics](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Analytics) |
| `get_sourcing_by_user`       | Sourced-candidate counts per recruiter                 | [Analytics](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Analytics) |
| `get_grading_analytics`      | Per-question grading stats for a job                   | [Analytics](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Analytics) |
| `get_top_candidates_for_job` | Top-ranked candidates for a job                        | [Analytics](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Analytics) |

### Applications

| Tool                                   | Description                                        | Public API                                                                   |
| -------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------- |
| `list_applications`                    | List applications with filtering                   | [Applicants](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Applicants) |
| `get_application`                      | Get a single application by Tenzo or remote ID     | [Applicants](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Applicants) |
| `get_application_by_candidate_and_job` | Resolve a (candidate, job) pair to its application | [Applicants](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Applicants) |
| `list_application_comments`            | ATS comments on an application                     | [Applicants](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Applicants) |
| `get_application_communications_email` | Email history for an application                   | [Applicants](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Applicants) |
| `get_application_communications_sms`   | SMS history for an application                     | [Applicants](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Applicants) |

### ATS

| Tool                                | Description                           | Public API                                                     |
| ----------------------------------- | ------------------------------------- | -------------------------------------------------------------- |
| `list_ats_integrations`             | ATS integrations enabled for your org | [ATS](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/ATS) |
| `get_ats_integration_configuration` | Configuration for one integration     | [ATS](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/ATS) |
| `list_ats_integration_rules`        | Sync rules for an integration         | [ATS](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/ATS) |

### Audit

| Tool                             | Description                      | Public API                                                         |
| -------------------------------- | -------------------------------- | ------------------------------------------------------------------ |
| `list_audit_events`              | Audit log events with filtering  | [Audit](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Audit) |
| `get_audit_event_filter_options` | Filter options for the audit log | [Audit](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Audit) |

### Calls & interviews

| Tool                     | Description                                    | Public API                                                                                                  |
| ------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `list_calls`             | List calls with filtering                      | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `get_call`               | Get a single call                              | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `get_call_transcript`    | Full call transcript                           | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `get_call_quality_eval`  | Quality-eval scores for a call                 | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `search_interviews`      | Search interviews by candidate, job, or status | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `list_interview_results` | Structured interview-result rows               | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `get_interview_results`  | Result rows for a single application           | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |

### Candidates

| Tool                                  | Description                                                | Public API                                                                   |
| ------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `list_candidates`                     | List candidates with filtering                             | [Candidates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Candidates) |
| `get_candidate`                       | Get a single candidate                                     | [Candidates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Candidates) |
| `search_candidates`                   | Search candidates by name                                  | [Candidates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Candidates) |
| `get_candidate_resume`                | Parsed resume for a candidate                              | [Candidates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Candidates) |
| `list_candidate_notes`                | ATS notes for a candidate                                  | [Candidates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Candidates) |
| `list_unanswered_candidate_questions` | Questions a candidate asked the AI that need a human reply | [Candidates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Candidates) |

### Jobs

| Tool                          | Description                              | Public API                                                       |
| ----------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `list_jobs`                   | List jobs with filtering                 | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `get_job`                     | Get a single job                         | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `search_jobs`                 | Rich job search with filters             | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `get_job_settings`            | Effective interview settings for a job   | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `get_job_script`              | Active script for a job                  | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `get_job_candidate_questions` | Candidate-facing FAQ for a job           | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `get_job_resume_requirements` | Resume requirements configured for a job | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |

### Folders

| Tool                   | Description                               | Public API                                                       |
| ---------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| `list_folder_contents` | Contents of a folder (jobs / sub-folders) | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |
| `search_folders`       | Search folders by name                    | [Jobs](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Jobs) |

### Media

| Tool             | Description                 | Public API                                                                                                  |
| ---------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `list_media`     | Audio/video assets metadata | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |
| `get_media_item` | A single media asset        | [Interviews, calls & media](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Interviews-calls-and-media) |

### Meeting Copilot

| Tool                             | Description                              | Public API                                                                             |
| -------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| `list_meeting_copilot_notes`     | List Meeting Copilot notes for your org  | [Meeting Copilot](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Meeting-Copilot) |
| `get_meeting_copilot_note`       | Get a single Meeting Copilot note        | [Meeting Copilot](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Meeting-Copilot) |
| `list_meeting_copilot_templates` | List Meeting Copilot templates (presets) | [Meeting Copilot](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Meeting-Copilot) |
| `get_meeting_copilot_template`   | Get a single Meeting Copilot template    | [Meeting Copilot](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Meeting-Copilot) |

### Docs

| Tool        | Description                            | Public API                                                                                 |
| ----------- | -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `list_docs` | List doc paths in the public docs tree | [Read-only Getters](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Read-only-Getters) |
| `get_doc`   | Get the markdown content of a doc      | [Read-only Getters](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Read-only-Getters) |

### Organization & users

| Tool                         | Description                 | Public API                                                                                 |
| ---------------------------- | --------------------------- | ------------------------------------------------------------------------------------------ |
| `get_org_interview_settings` | Org-wide interview defaults | [Organization](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Organization)           |
| `get_interview_rules`        | Active rules-engine rules   | [Organization](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Organization)           |
| `list_users`                 | List users in your org      | [Read-only Getters](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Read-only-Getters) |
| `get_user`                   | Get a single user           | [Read-only Getters](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Read-only-Getters) |
| `search_users`               | Search users by name        | [Read-only Getters](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Read-only-Getters) |

### Templates

Two tools cover every org-template family. Pass the family via the **`kind`** parameter instead of calling a per-family tool. Both map to the [`Templates`](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Templates) tag in the Public API.

| Tool             | Description                                                                    | Public API                                                                 |
| ---------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `list_templates` | List your org's templates of a given `kind` (optional `name` substring filter) | [Templates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Templates) |
| `get_template`   | Get one template by `kind` + `template_id`                                     | [Templates](https://api.tenzo.ai/v1/tenzo-api-documentation#tag/Templates) |

Allowed `kind` values: `script_generation`, `background_info`, `redaction`, `suggested_follow_up`, `voicemail_sms_prompt`, `flagged_event`, `summary`, `thank_you_email`, `custom_booking_outro`, `rejection_email`, `resume_feedback_email`, `interview_results_layout`, `question_constraints`.

<Note>
  The REST API keeps a dedicated endpoint per template family (e.g. `GET /api/v1/templates/summary`) — only the MCP tool surface is consolidated into `list_templates` / `get_template`.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The connector won't authorize / OAuth popup fails">
    Make sure you're signed in to Tenzo in the same browser. If you have multiple Tenzo accounts, sign out of the others first — the consent screen uses your active session to determine which organization to grant access to.
  </Accordion>

  <Accordion title="`401 Unauthorized` from a `.mcp.json` client">
    Your API key is missing, expired, or revoked. Re-export `TENZO_API_KEY` with a fresh key from **Settings → Developer Tools → API Keys** and restart your MCP client.
  </Accordion>

  <Accordion title="A tool returns `403 Forbidden`">
    The tool was called with an ID that belongs to a different organization. MCP tools only return data scoped to your org. Double-check the ID is one your account can see in the Tenzo dashboard.
  </Accordion>

  <Accordion title="A tool I expected isn't in the list">
    The MCP tools that proxy the [Public API](https://api.tenzo.ai/v1/tenzo-api-documentation) cover only its `GET` endpoints. Write operations on recruiting data (e.g. `POST /api/v1/job`) must be called via the REST API directly. (The assistant also has a `submit_feedback` tool that writes only to an internal feedback log, not to your recruiting data.)
  </Accordion>
</AccordionGroup>

## Related

* [API & Webhook Configuration](/settings/api-webhook-config) — generate the API key used by `.mcp.json` clients
* [Tenzo Public API Documentation](https://api.tenzo.ai/v1/tenzo-api-documentation) — full schemas for every underlying endpoint
* [Model Context Protocol specification](https://modelcontextprotocol.io/specification) — protocol details