Coffee Chats MCP quickstart

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 lists the hosts Coffee Chats accepts today.

The words used here are defined on the home page: connector, agent, agent host, permission, connection, review request, approval, credit, call.

Student path
Developer path

Add the connector to your agent host

Give your agent host this address:https://mcp.coffeechats.me/mcpA 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.

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 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.

Run this command:

Add the connector

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.

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.

Run this command:

Add the connector

codex mcp add coffeechats --url https://mcp.coffeechats.me/mcp --oauth-client-id codex

Then sign in:

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’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:

.cursor/mcp.json

{
  "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 lists all six with the client identifier each one uses.

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.

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.

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.

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 Code

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 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 lists all twenty-two with the tools each one unlocks.

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.

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 page gives the exact result.

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.

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 lists all 85 tools and marks each one as a read, a safe write, a consequential tool or a browser handoff.

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 explains what the review page shows you and what each outcome means.

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 says what a disconnect stops and what can still finish.

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.

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 page states each of these and what it counts.

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.

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:

profile.get input

{}

Read your data covers cursors, fragments and the texts a read failure can carry.

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:

profile.update input

{
  "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:

profile.update result

{
  "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 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.

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 works one of them through end to end, and withdraw a request takes one back.

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 gives the cause and the action for each. A 429 carries RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After.Error codes is the catalogue, and handle errors and retries 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.

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

What the tools reach, and what stays in the app.

Safe writes and approvals

The result object, and why nine changes wait for you.

Sign-in and credentials

The two sign-in paths and how long each credential lasts.

Read your data

The first guide for somebody writing the agent.

Get started

Chrome extension

How it works

Guides

Reference

About the credentials the agent host holds

Next steps

What an agent can do

Safe writes and approvals

Sign-in and credentials

Read your data

​About the credentials the agent host holds

​Next steps

What an agent can do

Safe writes and approvals

Sign-in and credentials

Read your data

About the credentials the agent host holds

Next steps