# Connect Markloop

You are connecting your user to Markloop, a review tool for the documents you write. You publish
an HTML document, people comment on exact spots, and you pull the comments back and publish the
next version. Everything goes through one remote MCP server:

```
https://app.markloop.io/api/mcp
```

Name the server `markloop`. Sign-in is OAuth in the browser, so there is no API key. Use the URL
exactly as written, with no trailing slash.

## 1. Check first

If you already have `markloop_*` tools, call `markloop_whoami`. If it lists a workspace, skip to
step 4.

## 2. Add the server

**If you can add MCP servers yourself, do it:**

- **Claude Code:** `claude mcp add --scope user --transport http markloop https://app.markloop.io/api/mcp`.
  If it says `markloop` already exists, run `claude mcp get markloop`. If the URL is different, ask
  the user before replacing it.
- **Codex** (the CLI and the Codex/ChatGPT desktop app share one config):
  `codex mcp add markloop --url https://app.markloop.io/api/mcp`, then `codex mcp login markloop`
- **Cursor:** add to `~/.cursor/mcp.json`:
  `{"mcpServers":{"markloop":{"url":"https://app.markloop.io/api/mcp"}}}`
- **VS Code / Copilot:**
  `code --add-mcp '{"name":"markloop","type":"http","url":"https://app.markloop.io/api/mcp"}'`
- **Gemini CLI:** `gemini mcp add --transport http markloop https://app.markloop.io/api/mcp`
- **Grok Bot:** create a custom MCP connector named `markloop` with the URL, then ask the user to
  approve the sign-in.
- **Any other client:** add a remote MCP server (streamable HTTP) with the URL above.

**If you are in a chat app, tell the user exactly what to click:**

- **Claude (web, desktop, mobile):** Customize > Connectors > Add custom connector, paste the URL,
  then Connect. One connection works everywhere on that Claude account. On Team or Enterprise, an
  Owner adds it under Organization settings > Connectors and everyone else clicks Connect.
- **ChatGPT:** Plugins > Add > Create custom MCP server, paste the URL, choose OAuth.
- **Grok:** grok.com/connectors > New Connector > Custom, paste the URL. On Grok Business or
  Enterprise, a team admin has to add it first.

Never say you added the server unless you actually ran the command or edited the file.

## 3. Sign-in

A browser window opens on Markloop. Tell the user what to expect:

- **They have an account:** sign in, choose which projects you may use, click **Allow**.
- **They don't have one yet:** click **Sign up** in that window. That starts a 14-day free trial
  with no card required. They create the account, workspace and first project in the same window,
  then click **Allow**.

The user types their password in the browser. Never ask for it and never create the account for
them.

**Claude Code:** a server added during a session shows up only after a restart. Ask the user to
exit and run `claude --continue` (that keeps this conversation), then type `/mcp`, pick `markloop`
and choose **Authenticate**.

## 4. Confirm

New tools often show up only after a restart. If `markloop_whoami` is not available yet, ask the
user to restart the client and then continue.

Call `markloop_whoami` and tell the user which workspace and projects you can reach. Then offer to
publish a document: `markloop_list_projects`, then `markloop_create_file`. Give the user the
`viewUrl` it returns, because that is the link to share with reviewers.

## If something goes wrong

- **"This link has expired":** sign-in took longer than ten minutes. Start Authenticate again.
- **"You have no projects you can connect an agent to":** the user is only a reviewer in that
  workspace. A workspace admin has to add them to a project.
- **A call says to re-authorize:** the user changed what they granted. Re-authorize Markloop in
  this client's MCP settings. Retrying the call will not help.
- **401 or the connection fails:** check the URL. It must be exactly
  `https://app.markloop.io/api/mcp`.

Help: hi@markloop.io