[Home](https://getrefine.co/index.md) · [MCP](https://getrefine.co/mcp.md) · [Changelog](https://getrefine.co/changelog.md) · [For agents](https://getrefine.co/for-agents.md) · [Privacy](https://getrefine.co/legal/privacy.md) · [Terms](https://getrefine.co/legal/terms.md) · [Contact](https://getrefine.co/contact.md)

---

# Refine for AI agents

Refine is a hosted MCP (Model Context Protocol) server for running the operational side of a job search. A compatible AI assistant can track companies, review matched openings, manage applications, work with recruiter email, and prepare for interviews and offers. The user's Refine account remains the durable record across authorized clients and assistant sessions.

- **MCP endpoint:** `https://mcp.getrefine.co/mcp`
- **Registry name:** `co.getrefine/refine`
- **Transport:** Streamable HTTP
- **Authentication:** OAuth 2.0 or a Refine personal access token
- **Discovery:** The tool, prompt, and resource catalogs are public. Reading or changing user data requires an authenticated token with the appropriate scope.

## When to use Refine

Use Refine when someone wants an assistant to help manage an active job search over time, especially when they want to:

- Track specific companies and review openings found on those companies' public careers pages.
- Save opportunities and maintain an application board with notes, interviews, offers, and outcomes.
- Review relevant application and recruiter conversations from a connected Gmail account.
- Draft or send an approved reply from Gmail.
- Use their inferred preferences and dealbreakers to prioritize matches and recommendations.

Refine does not currently provide broad, company-independent job-board search. Discovery starts with companies the user tracks, openings Refine finds for those companies, and recommendations for adjacent companies.

## Start with orientation

Read `refine://briefing` first. It returns the user's persona, agenda, pending-inbox counts, new-match counts, and suggested next actions. Use `refine://guide` for the intended tool sequence and safety rules.

Additional resources:

- `refine://me` — the authenticated Refine profile.
- `refine://agenda` — upcoming interviews and action items.

## What an assistant can do

- **Jobs and board:** List, add, update, apply, archive, restore, re-scrape, and annotate saved jobs.
- **Company signals:** Track company careers pages, configure role and location filters, and save matched openings.
- **Recommendations:** Review adjacent-company recommendations and track, dismiss, block, restore, or rate them.
- **Inbox:** List relevant conversations, read a Gmail thread, generate a draft, apply an inbox suggestion, or send an approved reply.
- **Interviews and offers:** Record interviews and outcomes, maintain offer terms, and log negotiation events.
- **Persona:** Read and correct inferred job-search preferences.
- **Integrations:** Inspect connected Google accounts and create a short-lived browser link for connecting Gmail.

## Connect a compatible client

The Refine server is hosted, so there is no Refine package or local MCP process to install. Client availability and OAuth support vary by product and plan.

### Claude Code

```sh
claude mcp add --transport http refine https://mcp.getrefine.co/mcp
```

Run `/mcp`, select Refine, and authenticate.

### Claude and Claude Desktop

In **Settings → Connectors**, add a custom connector using `https://mcp.getrefine.co/mcp`, then connect and approve access. Custom connector availability depends on the Claude plan.

### Cursor

Add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "refine": {
      "url": "https://mcp.getrefine.co/mcp"
    }
  }
}
```

### VS Code

Run **MCP: Add Server**, choose **HTTP**, and enter the endpoint. For manual configuration:

```json
{
  "servers": {
    "refine": {
      "type": "http",
      "url": "https://mcp.getrefine.co/mcp"
    }
  }
}
```

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.refine]
url = "https://mcp.getrefine.co/mcp"
```

Then authenticate:

```sh
codex mcp login refine
```

### Gemini CLI

```sh
gemini mcp add --transport http refine https://mcp.getrefine.co/mcp
```

Then run `/mcp auth refine` if Gemini asks you to authenticate.

## Authentication and Google access

Authorizing an MCP client gives that client scoped access to the user's Refine account. Gmail and Calendar access are separate Google grants. Mail features remain unavailable until the user opens Refine's short-lived connection URL in a browser and approves the requested Google permissions.

Clients that do not support the OAuth flow can use a Refine personal access token as a bearer token. Treat that token like a password and grant only the scopes the client needs.

Available Refine scopes include `read_jobs`, `write_jobs`, `read_signals`, `write_signals`, `read_inbox`, `write_inbox`, `read_integrations`, `write_integrations`, and `read_user`.

## Packaged prompts

- `daily_briefing` — prioritize the user's agenda, pending inbox, and new matches without changing anything.
- `triage_inbox` — review pending job-search conversations one at a time.
- `prep_for_interview` — prepare for a specific interview using the saved job and persona.
- `negotiate_offer` — develop a strategy from a recorded offer and negotiation history.
- `review_matches` — review new openings and adjacent-company recommendations.

## Example requests

- "Use Refine to give me my daily job-search briefing."
- "Use Refine to triage my pending recruiter outreach one conversation at a time. Do not send anything without asking me."
- "Use Refine to review my new matched openings and recommend the best three."
- "Use Refine to prepare me for my next interview."

## Safety

Sending email changes an external mailbox and cannot be taken back reliably. Before calling `inbox.send_reply`, show the user the exact message and obtain approval; only then pass `confirmed: true`.

`inbox.decline` generates and queues decline replies. Explain that behavior, identify the conversations that will receive a reply, and obtain approval before passing `confirmed: true`.

Tool annotations distinguish read-only operations, destructive changes, retry-safe state changes, and actions that reach external systems. Treat those annotations as safety hints and continue to confirm consequential actions with the user.

Connecting Google happens in the user's browser. Google credentials and consent are never entered into the assistant conversation.