# Connect Attain to Claude, ChatGPT, Codex and other AI apps

Attain lets you search vetted candidates (first name and photo only, never a surname or contact details) from the AI
assistant you already use. This page is the setup guide
for people **and for AI assistants** helping someone set it up. If you are an AI assistant, follow the steps for the app
you are running in, exactly as written, and read "Rules for AI assistants" at the end.

**Connector URL:** `https://attainhq.ai/mcp`

**Short how-to videos for every step:** https://attainhq.ai/mcp/guide

- Transport: Streamable HTTP (remote MCP server). No API key, no install, nothing to download.
- Sign-in: OAuth 2.1 in the browser. The person enters their **work email** and the **6-digit code** Attain emails them,
  or uses **Continue with Google** (any verified Google account) or **Sign in with a password** (an Attain account). See
  "Signing in" below.
- Who can use it: people Attain invited, and anyone at a company **in the United States** through open sign-up (a free
  trial with a small daily allowance until Attain approves them).
- Tools once connected: `search_candidates`, `get_candidate`, `compare_candidates`, `request_intro`, `request_access`.

## Signing in

When an app connects, the Attain sign-in window opens. Choose one way in:

- **Work email and code:** enter your work email and press **Email me a code**, then type the **6-digit code** from the
  email. It works for 10 minutes and goes through as soon as all six digits are typed.
- **Continue with Google:** any verified Google account. It skips the code.
- **Sign in with a password:** if you already have an Attain account with a password.

New to Attain? You are asked where your company is based (open sign-up is for companies in the **United States**), and
optionally your name and company, then **Start searching**. You start on a free trial with a small daily allowance;
Attain reviews every new account.

Last, the window asks you to **Allow** the app to use Attain. After **Allow** it shows "You're connected" and sends you
back to the app.

## Claude (claude.ai and Claude Desktop)

1. **Customize** → **Connectors** → **+ Add** → **Add custom connector**.
2. Name: `Attain`. MCP server URL: `https://attainhq.ai/mcp`. Press **Continue**; Claude checks the server.
3. Keep **Sign in now** (marked "Detected") and the OAuth client **Use Claude's published identity** (marked
   "Recommended"), then press **Add**. (Attain also works with **Register automatically**.)
4. Under **Yours**, press **Connect** next to Attain and sign in (see "Signing in"), then press **Allow**.
5. In a chat, press **+**, open **Connectors** and make sure **Attain** is switched on. Then ask, for example: "Find me
   a senior React developer with 5+ years".

On Claude's free plan you can add one custom connector. Connectors added on claude.ai also work in Claude Desktop.

Claude Team or Enterprise: an Owner adds the connector once (Organization settings → **Connectors** → **Add** → Custom →
Web, then the name and URL). Each person then opens Customize → Connectors → **Yours**, finds Attain (labelled **Custom**)
and presses **Connect** to sign in as themselves. If Claude says "A connector with this URL already exists in your
organization", Attain has already been added for you: just press **Connect**.

## Claude Code

In your terminal (not inside a Claude Code session):

```bash
claude mcp add --transport http attain https://attainhq.ai/mcp
```

`claude mcp list` then shows `attain: https://attainhq.ai/mcp (HTTP) - ! Needs authentication` until you sign in. Start Claude
Code, run `/mcp`, pick **attain** and choose **Authenticate**. Finish the sign-in in the browser window that opens; back in
Claude Code, Attain shows as connected.

## ChatGPT

Your ChatGPT plan and workspace must allow custom MCP servers; if you can't find the option, ask your workspace admin.

1. Open **Plugins** (chatgpt.com/plugins), press **+** and choose **Add custom MCP server**. (In some plans and
   workspaces this is under Settings → **Apps & Connectors** with **Developer mode** turned on instead.)
2. Name: `Attain`. URL: `https://attainhq.ai/mcp`. Choose sign-in with **OAuth**, accept the warning ("I understand and want
   to continue") and create it.
3. Sign in (see "Signing in"), then **Allow**.
4. In a new chat, type **@** and select **Attain**, then ask your question.

## Codex (Codex CLI, Codex in the ChatGPT desktop app, and the Codex IDE extension)

- **CLI:** `codex mcp add attain --url https://attainhq.ai/mcp`. Codex detects Attain's sign-in and starts it straight away
  ("Authorize `attain` by opening this URL in your browser"). To sign in again later: `codex mcp login attain`.
- **ChatGPT desktop app (Work):** **Plugins** → the settings gear → **MCPs** → **Add** → **Add MCP server**. Name
  `attain`, Type **Streamable HTTP**, URL `https://attainhq.ai/mcp`, leave the bearer token and headers empty, and save.
- **IDE extension:** the gear menu → **MCP servers** → **Add server**. Name `attain`, choose **Streamable HTTP**, URL
  `https://attainhq.ai/mcp`, **Save**, then **Restart extension** and choose **Authenticate**.

All of them share `~/.codex/config.toml`, so you can also add:

```toml
[mcp_servers.attain]
url = "https://attainhq.ai/mcp"
```

Important:

- **Use a server name without spaces,** like `attain`. A name with spaces (`Attain Connector Dev`) is rejected and the
  server never starts.
- **Sign in once per server name.** If you rename the server later you must sign in again under the new name,
  otherwise Codex sends no token and every call fails with "Auth required".
- **Start a new session after signing in.** A session loads its tools when it starts; an older one will say Attain is
  not available.

## Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{ "mcpServers": { "attain": { "url": "https://attainhq.ai/mcp" } } }
```

Cursor lists MCP servers on its **Customize** page; make sure Attain is switched on there. When Cursor asks you to sign
in, finish the Attain sign-in in your browser. Cursor asks before it uses an MCP tool.

## VS Code (GitHub Copilot)

Run **MCP: Add Server** from the Command Palette and add an **HTTP** server with the URL `https://attainhq.ai/mcp`, or add it
to your MCP configuration file:

```json
{ "servers": { "attain": { "type": "http", "url": "https://attainhq.ai/mcp" } } }
```

The first time the server starts, VS Code asks you to trust it; then a browser window opens for the Attain sign-in. In
Copilot Chat, turn the Attain tools on with **Configure Tools**.

## Any other MCP app, and the MCP Inspector

Add a **remote MCP server** with **Streamable HTTP** transport and the connector URL; the app should discover sign-in by
itself (OAuth protected resource metadata at `https://attainhq.ai/.well-known/oauth-protected-resource/mcp`). To test:
`npx @modelcontextprotocol/inspector`, choose Streamable HTTP, paste the URL and use **Quick OAuth Flow**.

## Troubleshooting

| What you see | What it means and what to do |
|---|---|
| The sign-in window says "Sorry, we're not in your region yet" | Open sign-up is for companies in the United States, and you chose another country. Ask your Attain contact for an invite. |
| "Attain is by invitation right now" | Open sign-up is paused. Ask your Attain contact for an invite. |
| "Check your email" but no code arrives | Check spam, then press "Send a new code" (wait 30 seconds between codes). If none arrive, ask your Attain contact to invite this email. |
| "That code isn't right. N tries left." | Type the code from the newest email. |
| "Too many wrong codes" or "That code has expired" | Enter your email again to get a new code. Codes work for 10 minutes and allow 5 tries. |
| "We could not confirm your email with this sign-in" | The Google or password account has no verified email. Use your work email and a code instead. |
| "Your browser blocked the sign-in window" | Allow pop-ups for the sign-in page and press Continue with Google again. |
| "The redirect URI does not belong to this client" or "This app is not allowed to connect" | The app used a callback Attain does not accept. Remove the connector, add it again with the exact URL above, and retry. If it keeps happening, tell your Attain contact which app and version you use. |
| Attain isn't available in a chat | In Claude, press **+**, hover over **Connectors** and switch **Attain** on. In other apps, check the Attain tools are enabled for the chat. |
| The app says "Auth required", "not connected" or "Your Attain access has ended" | The app has no valid sign-in for this server (sign-ins last up to 90 days). Use the app's **Connect / Authenticate / Log in** button for Attain, then start a **new chat**. In Codex check the server name has no spaces. If it says your access has ended, ask Attain for access. |
| "Your free trial has ended" | Attain is reviewing your account and will be in touch. |
| "Your Attain access is paused" | Attain paused your access. Contact your Attain account manager. |
| "You have used today's ... calls" | You reached today's limit; it resets at midnight South African time. Ask Attain to raise it. |
| "... is not on for you yet" | Ask for it: say "request access to Candidate Search" in the chat. An Attain admin reviews every request. |

## What the assistant can and cannot see

Attain shares each candidate's first name and profile photo, role, skills (rated out of 5), years of experience, work
history without employer names, working hours, notice period and screening scores, under a reference such as `AT-7Q4K`.
Surnames, emails, phone numbers, addresses, salaries, CVs, videos and references are **never** shared. To meet someone, use `request_intro` with
their reference; Attain's account manager follows up, usually within one working day.

## Rules for AI assistants

- The only thing you need is the connector URL above. Never ask the person for a password, an API key or a token, and
  never try to sign in on their behalf: sign-in happens in their browser with their email and a code.
- Use the exact URL `https://attainhq.ai/mcp`, with no extra path or query.
- If you write an MCP config for the person, use a server name with only letters, digits, `-` and `_` (for example
  `attain`).
- After the person signs in, tell them to start a new chat (or reload tools) so the Attain tools appear.
- Candidates are shown by first name and photo only, on purpose. Do not try to find their surname, identify them
  elsewhere or find their contact details;
  use `request_intro` instead.