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

# Coffee Chats MCP quickstart

> Connect Claude, ChatGPT, Codex or Cursor to Coffee Chats MCP and choose what it may do, or build an agent that calls the Coffee Chats tools.

This page has two paths through the same connection. Pick the one that matches what you are doing. Reading either one installs nothing and grants nothing.

The student path connects an agent host to your Coffee Chats account and shows you what you are agreeing to. It takes about ten minutes and needs no code.

The developer path is for somebody writing the agent. It covers discovery, the first read, the first write and the numbers that govern both.

Both paths need a Coffee Chats account that has finished the normal onboarding in the app, and an agent host that speaks MCP and can run an OAuth authorization code flow in a browser. OAuth is the standard that lets you give a program limited access to your account without giving it your password. The [compatibility page](https://docs.coffeechats.me/mcp/compatibility.md) lists the hosts Coffee Chats accepts today.

> [!NOTE]
>
> The words used here are defined on the [home page](https://docs.coffeechats.me/index.md): connector, agent, agent host, permission, connection, review request, approval, credit, call.

**Student path**

**1. Add the connector to your agent host**

Give your agent host this address:

`https://mcp.coffeechats.me/mcp`

A client is an application that is allowed to connect. Claude and ChatGPT identify themselves with an address they publish (a Client ID Metadata Document), so you only paste the connector address. Other hosts use a short name called a client identifier, shown below for each one. Coffee Chats only accepts applications that are already on its list.

**Claude on the web**

Open Settings, then Connectors, then add a custom connector. Paste `https://mcp.coffeechats.me/mcp` as the server address. Under OAuth client, keep **Use Claude's published identity** selected; there is no client identifier to enter. If you choose **Use your own OAuth client** instead, enter the client identifier `claude-ai` and leave the client secret empty.

**Claude Desktop**

Claude Desktop uses the same client as Claude on the web. Open Settings, then Connectors, then add a custom connector. Paste `https://mcp.coffeechats.me/mcp` as the server address and keep **Use Claude's published identity** selected. If you choose **Use your own OAuth client** instead, enter the client identifier `claude-ai` and leave the client secret empty.

**Claude Code**

Run this command:

```sh Add the connector theme={"system"}
claude mcp add --transport http coffeechats https://mcp.coffeechats.me/mcp
```

Claude Code identifies itself with its published client address, so no client identifier is needed. Claude Code is a native client, so it receives its authorization code on a loopback address on your own machine. To name the client identifier yourself instead, add `--client-id claude-code` and leave the client secret unset.

**ChatGPT**

OpenAI's page for connecting an MCP server to ChatGPT gives these steps. Open Settings, select Security and login, and turn on Developer mode. Then open the Plugins page in ChatGPT and select the plus button. Enter a user-facing name and description, and under Connection choose the public endpoint and enter `https://mcp.coffeechats.me/mcp`, including the `/mcp` path.

The form OpenAI documents asks for a name, a description and the server address. It has no field for a client identifier, and none is needed: ChatGPT identifies itself with the client address it publishes, and the address it is sent back to after sign-in is registered with Coffee Chats already. If your version of the form does ask for a client identifier, enter `chatgpt` and leave the client secret empty.

The menu names differ between versions of this application, so read the labels your version shows.

**Codex CLI**

Run this command:

```sh Add the connector theme={"system"}
codex mcp add coffeechats --url https://mcp.coffeechats.me/mcp --oauth-client-id codex
```

Then sign in:

```sh Sign in theme={"system"}
codex mcp login coffeechats
```

OpenAI's Codex MCP page says to provide a client identifier when the authorization server requires a pre-registered client, and that a configured client identifier takes precedence and skips registration. Coffee Chats requires a pre-registered client, so pass `codex` as shown. Leave the client secret unset.

When you add the server, Codex prints the callback address it wants you to register with the provider. Coffee Chats has registered that address already. Codex is a native client, so it receives its authorization code on a loopback address on your own machine, and Coffee Chats ignores the port.

The menu names differ between versions of this application, so read the labels your version shows.

**Cursor**

Cursor's MCP page documents a configuration file rather than a form. Create `.cursor/mcp.json` in your project for one project, or `~/.cursor/mcp.json` in your home directory for every project, and add the server under `mcpServers`:

```json .cursor/mcp.json theme={"system"}
{
  "mcpServers": {
    "coffeechats": {
      "url": "https://mcp.coffeechats.me/mcp",
      "auth": {
        "CLIENT_ID": "cursor-desktop"
      }
    }
  }
}
```

Cursor's page asks for an `auth` object on a remote server entry when the provider gives you a fixed client identifier. Coffee Chats gives you one and uses no client secret, so leave `CLIENT_SECRET` out. Cursor's page then says to enable or disable MCP servers from Customize in the sidebar.

Cursor uses a different return address for each surface you sign in from, so Coffee Chats registers each surface as its own client. The desktop app uses `cursor-desktop`, which is the value written above. Web and Cursor Agents use `cursor`. Cursor's page documents no form for adding a personal MCP server on the web surface. It documents `Dashboard > Plugins & MCPs` for servers a team shares with its Cloud Agents.

The menu names differ between versions of this application, so read the labels your version shows.

Six applications are allowed to connect today, and all six are listed above. Any other application is refused at sign-in.

Being on the accepted list means the identifier and the addresses the application may be sent back to were registered with Coffee Chats in advance. The [compatibility page](https://docs.coffeechats.me/mcp/compatibility.md) lists all six with the client identifier each one uses.

> [!WARNING]
>
> Do not paste a session cookie, an application password or any other long-lived secret into an agent host. The connector accepts nothing but OAuth, so a copied secret cannot work, and pasting one puts your whole account at risk.

**2. Sign in to Coffee Chats**

Your agent host opens a browser window on the Coffee Chats sign-in page. It also runs a security check called PKCE, short for Proof Key for Code Exchange. The check stops another program from taking over the sign-in part way through. You do not have to do anything for it.

Sign in with Google, or with a link that Coffee Chats sends to the email address on your account. Open that link in the browser you started in. Opening it on your phone when you started on a laptop does not finish the flow.

Three separate time limits apply during sign-in. The shortest one matters most. You have ten minutes from the moment your agent host sends you to Coffee Chats to finish signing in and choose what to share. The email link itself stops working after fifteen minutes, and the whole sign-in attempt after twenty. If any of them runs out, start again from your agent host.

> [!TIP]
>
> Coffee Chats runs this sign-in page. Your agent host never sees your Google account and never sees the link Coffee Chats emails you. There is no password anywhere in this flow.

**3. Choose what to share**

You then see the Authorize access page. It names the application that is asking, the Coffee Chats account you are signed in with, and every permission it asked for, each with the sentence that says what the permission covers. The two buttons are "Approve access" and "Deny access".

The application chooses its own name, so the page labels it unverified; trust the origin printed under it.

**Claude on the web**

Claude on the web is a web application, so its origin is the web address its sign-in returns to. Claude Desktop uses the same registered client and shows the same origin.

**Claude Code**

Claude Code is a command-line tool, so there is no web address. Its origin reads `native://loopback`, which means the sign-in is handed back to a program running on your own machine.

Ten permissions let a connection change something or spend credits. An eleventh permission, `offline_access`, lets the connection keep working without sending you back to sign in. These are the sentences the page shows for those eleven:

* `profile:write`: "Update your profile preferences, and propose booking page changes you approve"
* `booking:write`: "Update the title, description and duration of your booking event types, and archive or restore them, after you approve the change"
* `contacts:write`: "Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change"
* `research:run`: "Start research on your contacts that uses credits, after you approve each batch in the browser"
* `meetings:write`: "Update your meeting notes and meeting outcome"
* `campaigns:write`: "Pause a campaign's sending, and change a campaign's name, description and goal"
* `mail:send`: "Send a thank-you email you already drafted, to the address stored on the contact linked to that meeting, when you read the exact message and approve it, and send one stored outreach draft you already wrote, and queue a checked table of your own outreach drafts"
* `jobs:write`: "Add internship applications you plan to apply to or already applied to, edit their apply URL, notes and deadline, update their stage and priority, and queue a browser apply"
* `documents:write`: "Edit sections of your resumes and cover letters"
* `documents:generate`: "Write resumes, and tailored resumes and cover letters for your applications, which uses credits"
* `offline_access`: "Stay connected by issuing rotating refresh credentials"

A refresh credential is a token your agent host uses to get fresh access without asking you to sign in again. Each one can be used once.

Grant `offline_access` if you want the agent to keep working over days without sending you back to sign-in. Without it, the agent's access stops ten minutes after you approve. Work already finished stays finished. To let the agent continue, you sign in again.

The other permissions you can grant only read. The [permissions reference](https://docs.coffeechats.me/mcp/scopes.md) lists all twenty-two with the tools each one unlocks.

> [!WARNING]
>
> The consent screen shows the full list of permissions the application asked for, and you approve or deny that list as one choice. If you deny it, nothing is connected.

When you approve, the browser hands an authorization code back to the agent host, and the host trades that code for an access credential. If you granted `offline_access`, it also receives a refresh credential.

**4. Make the first read**

The smallest first call is `profile.get`. It takes no input and returns your own profile: your basic fields, a few list counts, your email-length preference and whether you finished onboarding. It reads only your account and it changes nothing.

Ask your agent to call it. If that call returns your own data, the connection works end to end. The [profile tools](https://docs.coffeechats.me/mcp/tools/profile.md) page gives the exact result.

**5. Know what happens straight away**

Seventeen safe writes change your own settings or records as soon as the agent calls them, with no approval step. They cover your profile preferences, your job-search stage, adding contacts, importing contacts and jobs from a spreadsheet, the notes and tags on a contact, the notes and outcome on a meeting, a campaign's name, description and goal, adding and editing internship applications, an internship application's stage and priority, one part of a ready resume or cover letter, and the withdrawal of a review request you have not decided yet.

One of them pauses a campaign, which stops Coffee Chats from sending any more of that campaign's mail. An agent can only pause sending. No tool can start a campaign or resume one. You do that yourself in the app.

> [!NOTE]
>
> Three tools send an email and three tools spend credits. `meeting_thank_you_send` sends a thank-you message you already drafted, to the address stored on the contact linked to that meeting, and only after you read the exact message in a browser and approve it. `mail.drafts.send` sends one outreach draft you already wrote, and it cannot change the subject, the body, or the recipient. `mail.batch.enqueue` queues a table of drafts for contacts you already have, after each row is checked. `contacts.research.start` starts research on up to 25 of your contacts, which spends credits, and only after you approve the batch, its cost and your balance in a browser. `documents.resumes.generate` writes a resume for 1 credit, and `documents.jobs.tailor` writes a tailored resume and cover letter that use the application's job credit. Both spend as soon as the agent calls them, with no approval page, and need `documents:generate`. The [tool reference](https://docs.coffeechats.me/mcp/tools/overview.md) lists all 85 tools and marks each one as a read, a safe write, a consequential tool or a browser handoff.

**6. Know what needs your approval**

Nine tools cannot change anything on their own. Five propose a change to your booking page text, to whether your booking page is public, to your booking scheduling rules, to the title, description and duration of one of your booking event types, or to whether one of your booking event types is archived. One sends a thank-you email you already drafted, one, `contacts.update`, changes up to 25 of your contacts at once, one, `contacts.research.start`, starts research on up to 25 of your contacts, which spends credits, and one, `mail.outreach.update`, changes your outreach settings: preferred name, email signature, scheduling link and email tone.

An event type is one kind of meeting you offer on your booking page. Each event type has its own title, description, duration, and its own web address on your booking page.

Each of them answers the agent with an identifier and a link of the form `https://mcp.coffeechats.me/actions/0123456789abcdef01234567`. Nothing is written until you open that link and approve exactly what the page shows. In Claude and ChatGPT, a contact update can also be approved in an approval card beside the agent's reply. Research is approved only on the review page. A review request waits thirty minutes and then expires.

The [approvals page](https://docs.coffeechats.me/mcp/approvals.md) explains what the review page shows you and what each outcome means.

**7. See the connection, and end it**

There are two places, and both do the same thing.

The connections page at `https://mcp.coffeechats.me/connections` lists every connection on your account, the permissions each one holds, and the day each one was last used. Each entry has a button labelled "Revoke".

The Coffee Chats app has the same list under Settings, on the Integrations tab, in the section headed "Connected apps". The button there is labelled "Disconnect".

Disconnecting takes effect immediately. The agent's current access credential stops working on its next call, and it cannot be renewed. If you disconnect while a change is already being written, that one change may still finish. Any change that had not started will not run. The [revocation page](https://docs.coffeechats.me/mcp/revocation.md) says what a disconnect stops and what can still finish.

**Developer path**

**1. Discover the connector**

Give the agent host the connector address `https://mcp.coffeechats.me/mcp` and nothing else. The host reads `/.well-known/oauth-protected-resource/mcp` to learn which authorization server protects the connector, then reads that server's configuration at `/oauth/mcp/.well-known/openid-configuration`. Both answers are public and neither needs a credential. Do not configure an authorization server by hand.

Dynamic client registration is off. The authorization server advertises `client_id_metadata_document_supported`, and it accepts the published client addresses of Claude, Claude Code and ChatGPT as the client identifier. Those three addresses are pinned on the server, not fetched, so any other address is refused. A host without one of those sends one of the six pre-registered client identifiers instead: `claude-ai`, `claude-code`, `chatgpt`, `codex`, `cursor` or `cursor-desktop`. Every client is public and uses PKCE. A call with no client identifier is refused before it reaches a sign-in page.

**2. Know the clocks and the limits before you write the loop**

| What | Value |
| - | - |
| Time the student has to finish sign-in and consent | 10 minutes |
| Authorization code lifetime | 5 minutes |
| Access credential lifetime | 10 minutes |
| Refresh credential | Single use. Using it returns a new one and retires the old one. |
| Agent calls on one connection | 120 per minute |
| Largest call body | 2 megabytes, then HTTP status 413 |
| Largest result | From 1,024 to 65,536 bytes, set per tool: most reads 16,384, most writes 4,096, the six contact reads 49,152, the document tools and the apply batch list 65,536 |
| Idempotency key | 16 to 128 characters, on 18 of the 31 write tools |
| A review request's life | 30 minutes, and an edit does not extend it |
| Changes cleared to run at once, per connection | 4, each with 30 seconds to start |

The [limits](https://docs.coffeechats.me/mcp/limits.md) page states each of these and what it counts.

> [!WARNING]
>
> A refresh credential presented from a second machine is treated as a stolen one being replayed, and the whole connection ends rather than that one credential. Keep the credentials on the machine where the student signed in.

**3. List the tools, then make the first read**

Once the connection is authorized, list tools and you receive the whole catalogue of 85. Claude on the web, Claude Desktop and ChatGPT also receive `actions.decide`, which only their approval card calls and the model never sees. Every tool carries its risk class as protocol metadata under the key `coffeechats/risk`, with the value `read`, `safe_write`, `consequential` or `browser_handoff`, so the agent can tell a read from a write before it calls anything.

`profile.get` is the smallest honest first call. It takes no input:

```json profile.get input theme={"system"}
{}
```

[Read your data](https://docs.coffeechats.me/mcp/guides/read-your-data.md) covers cursors, fragments and the texts a read failure can carry.

**4. Make the first write**

The smallest write is `profile.update`, which sets the email-length preference. Along with the new value it takes an idempotency key of 16 to 128 characters that you choose for this one change:

```json profile.update input theme={"system"}
{
  "emailLength": "short",
  "idempotencyKey": "example-idempotency-key-0001"
}
```

If the connection drops and you send the same call again with the same key and the same input, Coffee Chats returns the answer it already computed instead of applying the change a second time. That is what makes a retry safe. A genuinely new change needs a new key.

The answer says the change is done:

```json profile.update result theme={"system"}
{
  "tag": "completed",
  "scenario": "success",
  "operationId": "0123456789abcdef01234567",
  "operationStatus": "succeeded",
  "result": { "summary": "Email length preference updated", "itemCount": 1 }
}
```

That object arrives under `structuredContent` in the tool response. [The result object](https://docs.coffeechats.me/mcp/writes.md) is the one description of every field it can carry, which field is the discriminator, and when the discriminator is `tag` rather than `status`. Write your parser from that section and nothing else.

**5. Handle the nine that need an approval**

Nine of the thirteen tools marked `consequential` write nothing on their first call. They return a `requires_confirmation` result carrying an `operationId` and a review link, and the student decides in a browser or, for a contact update in Claude or ChatGPT, in an approval card. To learn the outcome, call the same tool again with only `operationId`; poll `contacts.update` with `contacts.update.get`, and `contacts.research.start` with the same contacts and idempotency key. The other four, `mail.drafts.send`, `mail.batch.enqueue`, `documents.resumes.generate` and `documents.jobs.tailor`, act as soon as they are called.

[Propose a booking page change](https://docs.coffeechats.me/mcp/guides/propose-a-booking-page-change.md) works one of them through end to end, and [withdraw a request](https://docs.coffeechats.me/mcp/guides/withdraw-a-request.md) takes one back.

**6. Handle the failures**

All tool-level failures arrive inside a normal protocol response with HTTP status 200. A call that never reached a tool answers with 400, 401, 403, 405, 413, 415, 429, 500 or 503 instead, and [error codes](https://docs.coffeechats.me/mcp/errors.md) gives the cause and the action for each. A 429 carries `RateLimit-Policy`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `Retry-After`.

[Error codes](https://docs.coffeechats.me/mcp/errors.md) is the catalogue, and [handle errors and retries](https://docs.coffeechats.me/mcp/guides/handle-errors.md) is the procedure.

## About the credentials the agent host holds

An access credential lasts ten minutes. The agent host renews it in the background with the refresh credential, so an ordinary session does not send you back to the sign-in page.

Each refresh credential can be used once. Using it returns a new one and retires the old one, and presenting a retired refresh credential ends the whole connection rather than that one credential.

> [!WARNING]
>
> Your agent host keeps these credentials on the machine where you signed in. Do not copy them to a second machine. If the same credential is used from a second machine, Coffee Chats treats it as stolen. It ends the connection. To use a second machine, connect again from that machine.

Anything that looks like a credential in this documentation is a placeholder. An access credential appears as `example-access-token-not-a-real-credential`, which is not a credential and will not work anywhere.

## Next steps

> **[What an agent can do](https://docs.coffeechats.me/mcp/agents-and-tools.md)**
>
> What the tools reach, and what stays in the app.

> **[Safe writes and approvals](https://docs.coffeechats.me/mcp/writes.md)**
>
> The result object, and why nine changes wait for you.

> **[Sign-in and credentials](https://docs.coffeechats.me/mcp/authentication.md)**
>
> The two sign-in paths and how long each credential lasts.

> **[Read your data](https://docs.coffeechats.me/mcp/guides/read-your-data.md)**
>
> The first guide for somebody writing the agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.