Reactive-Resume/docs/guides/using-the-mcp-server.mdx

---
title: "Using the MCP Server"
description: "Connect Reactive Resume to AI tools like Claude Desktop, Cursor, and Codex using the Model Context Protocol"
---

The Reactive Resume MCP server lets you manage and modify your resumes through any MCP-compatible AI tool — Claude Desktop, Cursor, Codex, and more. It connects to the Reactive Resume API and exposes tools for listing, reading, and patching resumes using natural language.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standard that lets LLM-powered tools connect to external services. Instead of being limited to the built-in chat UI, you can use any MCP client to interact with your resumes.

## Prerequisites

<Steps>
  <Step title="Choose your authentication method">
    Reactive Resume MCP supports two authentication methods:

    - **OAuth2 (recommended):** best user experience for clients that support MCP OAuth.
    - **API key (fallback):** works in all clients that can send custom headers.

    Use OAuth2 whenever your MCP client supports it. Use API key only when OAuth is unavailable in that client.

  </Step>

  <Step title="If using API key, create one">
    Head over to [https://rxresu.me](https://rxresu.me) (or your self-hosted instance), sign in, and navigate to **Settings → API Keys**. Click **Create a new API key**, give it a name, and copy the secret — it's only shown once.

    For the full walkthrough, see [Using the API](/guides/using-the-api).

  </Step>
</Steps>

## Configuration

There are two transport options, and each can use either OAuth2 or API key depending on your client capabilities.

### Method 1: Streamable HTTP (recommended)

If your client supports the `url` field (e.g. **Cursor**, **Codex**, Claude custom connectors), use this.

#### Option A: OAuth2 (recommended)

Most OAuth-capable clients only need the MCP URL:

```json
{
  "mcpServers": {
    "reactive-resume": {
      "url": "https://rxresu.me/mcp"
    }
  }
}
```

Then connect/sign in from the client UI (or with the client's OAuth login command).

#### Option B: API key (fallback)

If OAuth is not supported in your client, send `x-api-key`:

```json
{
  "mcpServers": {
    "reactive-resume": {
      "url": "https://rxresu.me/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}
```

### Method 2: mcp-remote

If your client only supports `command` / `args` (for example, local-only Claude Desktop config), use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge. This requires [Node.js](https://nodejs.org) **20 or later**.

`mcp-remote` is most commonly used with API keys:

```json
{
  "mcpServers": {
    "reactive-resume": {
      "command": "npx",
      "args": ["mcp-remote", "https://rxresu.me/mcp", "--header", "x-api-key:your-api-key"]
    }
  }
}
```

<Info>Replace `your-api-key` with the API key you created in the prerequisites step.</Info>

### Where to put the config

| Client            | Config file                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| Cursor            | `.cursor/mcp.json` in your project or home directory                                             |
| Claude Desktop    | `claude_desktop_config.json` ([docs](https://modelcontextprotocol.io/quickstart/user))           |
| Codex             | `~/.codex/config.toml` or `.codex/config.toml` ([docs](https://developers.openai.com/codex/mcp)) |
| Other MCP clients | Refer to the client's documentation                                                              |

## Authentication Details (How Reactive Resume MCP Works)

Reactive Resume MCP accepts authentication in this order:

1. **Bearer token (OAuth2 access token)** via `Authorization: Bearer <token>`
2. **API key fallback** via `x-api-key: <key>`

If neither is valid, the MCP endpoint responds with `401` and advertises OAuth metadata using:

- `WWW-Authenticate: Bearer resource_metadata="<instance>/.well-known/oauth-protected-resource"`

This lets OAuth-capable MCP clients discover and complete the OAuth flow automatically.

### OAuth2 flow used by this server

Reactive Resume is configured as an OAuth authorization server for MCP clients:

- The MCP endpoint is `https://rxresu.me/mcp`.
- OAuth discovery metadata is exposed under `/.well-known/*` endpoints.
- The login/authorization route is `/auth/oauth`.
- If the user is not signed in, `/auth/oauth` redirects to `/auth/login`, then resumes OAuth.
- If the user is signed in, `/auth/oauth` validates `client_id` and `redirect_uri`, issues an authorization code, and redirects back to the client.
- PKCE parameters (`code_challenge`, `code_challenge_method`) are preserved in the authorization flow.

## Popular Client Setup

### Cursor

**OAuth2 (recommended):**

```json
{
  "mcpServers": {
    "reactive-resume": {
      "url": "https://rxresu.me/mcp"
    }
  }
}
```

**API key fallback:**

```json
{
  "mcpServers": {
    "reactive-resume": {
      "url": "https://rxresu.me/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}
```

### Codex (CLI / IDE extension)

Add server:

```bash
codex mcp add reactive-resume --url https://rxresu.me/mcp
```

Then log in with OAuth:

```bash
codex mcp login reactive-resume
```

API key fallback (`config.toml`):

```toml
[mcp_servers."reactive-resume"]
url = "https://rxresu.me/mcp"
http_headers = { "x-api-key" = "your-api-key" }
```

### Claude (web app custom connector)

Add `https://rxresu.me/mcp` as a custom remote MCP connector, then connect with OAuth in Claude's connector UI.

### Claude Desktop (local config file)

Use `mcp-remote` bridge with API key (example shown above in **Method 2**).

## External References

- [Cursor MCP docs](https://cursor.sh/docs/mcp)
- [MCP quickstart for users (Claude Desktop example)](https://modelcontextprotocol.io/quickstart/user)
- [OpenAI Codex MCP docs](https://developers.openai.com/codex/mcp)
- [Claude custom connectors (remote MCP)](https://claude.com/docs/connectors/custom/remote-mcp)
- [MCP Authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization)

## Self-Hosting

If you're running a self-hosted Reactive Resume instance, replace `https://rxresu.me/mcp` with your instance URL:

```json
{
  "url": "https://resume.example.com/mcp",
  "headers": {
    "x-api-key": "your-api-key"
  }
}
```

## Available Tools

Tool names use canonical unprefixed `snake_case` names.

| Tool                    | Description                                                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `list_resumes`          | List all resumes with IDs, names, tags, and status. Supports filtering by tags and sorting by last updated, creation date, or name |
| `list_resume_tags`      | List every distinct tag in use across your resumes (sorted)                                                                        |
| `read_resume`           | Get the full data of a specific resume by ID                                                                                       |
| `get_resume_analysis`   | Get the latest saved AI analysis for a resume (from the web app), if any                                                           |
| `create_resume`         | Create a new, empty resume with a name and slug. Optionally pre-fill with sample data                                              |
| `import_resume`         | Create a resume from a full ResumeData JSON export (random name/slug). Large files may exceed client limits                        |
| `duplicate_resume`      | Create a copy of an existing resume with a new name and slug                                                                       |
| `apply_resume_patch`    | Apply JSON Patch (RFC 6902) operations to modify a resume's data                                                                   |
| `update_resume`         | Update metadata only: name, slug, tags, `isPublic`. Returns canonical share URL; passwords are not managed via MCP                 |
| `delete_resume`         | Permanently delete a resume and all associated files. **Irreversible**                                                             |
| `lock_resume`           | Lock a resume to prevent edits, patches, and deletion                                                                              |
| `unlock_resume`         | Unlock a previously locked resume to re-enable editing                                                                             |
| `get_resume_statistics` | Get view and download statistics for a resume                                                                                      |

### Breaking change (tool names)

Older clients may refer to prefixed or dot-separated names. Those names are no longer registered; update automations and saved prompts to the canonical names above.

## Available Resources

Resources follow MCP conventions: **static** items appear in `resources/list`; **parameterized** access is declared in `resources/templates/list` and read via `resources/read` once you know the ID.

| Discovery                             | What you get                                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------------------------- |
| `resources/list`                      | Static resources only — currently **`resume://_meta/schema`** (ResumeData JSON Schema)        |
| `resources/templates/list` | **`resume://{id}`** — template for reading full resume JSON by ID (not enumerated per resume) |
| `list_resumes` (tool)      | **Primary way to discover resume IDs** — resumes are not listed as separate MCP resources     |

| URI                     | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `resume://_meta/schema` | ResumeData JSON Schema — use for valid JSON Patch paths and value types  |
| `resume://{id}`         | Full resume data as JSON — use an ID from `list_resumes`                 |

### Breaking change (schema URI)

The schema resource was previously `resume://schema`. It is now **`resume://_meta/schema`**. Update any saved prompts, automations, or client configs that referenced the old URI.

### Static server card (`/.well-known/mcp/server-card.json`)

`GET /.well-known/mcp/server-card.json` returns a JSON document ([SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649)) with `serverInfo`, optional authentication metadata, and summaries of tools, resources, resource templates, and prompts. It is generated to match the live MCP server and can be used for discovery when a client cannot run a full capability scan against `/mcp/`.

## Available Prompts

Prompts are pre-built workflows that provide the AI with structured instructions and context. Each prompt embeds the resume data and the schema resource (`resume://_meta/schema`) automatically.

| Prompt           | Description                                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `build_resume`   | Guide you step-by-step through building a resume from scratch — basics, summary, experience, education, skills, and design                                   |
| `improve_resume` | Review your resume and suggest concrete improvements to wording, impact, metrics, and structure                                                              |
| `review_resume`  | Get a structured, professional critique with a scorecard (1–10 across seven dimensions) and prioritized recommendations. **Read-only** — no changes are made |

## Usage Examples

Once your MCP client is connected, you can use natural language to interact with your resumes:

### Browsing

- "List my resumes"
- "Show me my resume named 'Software Engineer'"
- "What skills are listed on my resume?"
- "Show me the stats for my resume"

### Creating & Managing

- "Create a new resume called 'Frontend Engineer 2026'"
- "Import this exported ResumeData JSON as a new resume"
- "What tags do I use across my resumes?"
- "Duplicate my 'Software Engineer' resume for a product manager role"
- "Make my resume public and give me the share link"
- "Lock my finalized resume so it can't be accidentally edited"
- "Delete my old draft resume"

### Editing

- "Update my name to Jane Doe"
- "Change my headline to Senior Software Engineer"
- "Add TypeScript to my skills with an Advanced proficiency level"
- "Add a new experience entry for my role as Staff Engineer at Acme Corp from Jan 2024 to Present"
- "Remove the third item from my skills section"

### Styling

- "Change the template to bronzor"
- "Set the primary color to blue"
- "Hide the interests section"

### Using Prompts

- "Help me build my resume from scratch" (uses `build_resume`)
- "Review my resume and give me a score" (uses `review_resume`)
- "Improve the wording on my resume" (uses `improve_resume`)

<Tip>
  The AI will use `read_resume` to inspect your current resume before making changes with `apply_resume_patch`. This
  ensures the correct JSON paths are used. Use `update_resume` for name, slug, tags, and public visibility (not for
  section content).
</Tip>

## Troubleshooting

| Issue                                                         | Solution                                                                                                                       |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| "Unauthorized" with no login prompt                           | Your client may not support MCP OAuth discovery. Use API key mode (`x-api-key`)                                                |
| OAuth login opens but fails redirect/callback                 | Confirm your client's MCP OAuth callback settings and retry the connection                                                     |
| "API error (401)"                                             | Your API key is invalid or expired. Create a new one in **Settings → API Keys**                                                |
| "API error (404)"                                             | The resume ID doesn't exist. Use `list_resumes` to find valid IDs                                                             |
| "API error (403)"                                             | The resume is locked. Unlock it in the Reactive Resume dashboard                                                               |
| Connection refused                                            | Check that the URL is correct and the instance is running                                                                      |
| "ReferenceError: File is not defined" when using `mcp-remote` | You're running Node.js 18. `mcp-remote` requires **Node.js 20 or later** — upgrade with `nvm use 20` or `nvm alias default 20` |