> Step-by-step setup for Claude, Claude Code, ChatGPT, Codex, Cursor, VS Code, Gemini and any other MCP client

# Connect an app

Every client needs the same two things: your MCP endpoint, and one trip through the OAuth consent
screen. The steps below differ only in where each client hides its connector form.

Open [Settings > Connect Pylo](https://app.pyloapp.com/p/settings/connected-apps) in the admin panel
first. It shows your endpoint with the customer id already filled in, a connector name of the form
`pylo-<customer>`, and a **Copy instructions to share** button that puts the whole setup for one
client on your clipboard, ready to send to whoever runs it. Every example below writes the endpoint
as `https://<your-pylo-mcp-host>/mcp/<customer-id>` and the name as `pylo`.

> **Naming the connector**
> Name each connector after its customer. Clients list every connector in one flat menu, so
> `pylo-acme` and `pylo-northwind` stay apart where two `pylo` entries would not. Claude Code
> accepts only letters, numbers, hyphens and underscores in a name.

## Claude

Covers claude.ai and Claude Desktop. Both use the same connector form.

1. Open Claude, then **Settings > Connectors**.
2. Choose **Add custom connector**.
3. Fill in **Name** (`pylo`) and **Remote MCP server URL**
   (`https://<your-pylo-mcp-host>/mcp/<customer-id>`).
4. Leave **OAuth Client ID**, **OAuth Client Secret** and every other field blank.
5. Save, then approve Pylo in the window Claude opens.

> **Enable it in the chat**
> Adding the connector is not enough. Claude offers Pylo's tools only once you enable the connector
> from the tools menu in a conversation.

## Claude Code

```bash filename="terminal"
claude mcp add --transport http pylo https://<your-pylo-mcp-host>/mcp/<customer-id>
```

The server is added to the current project. Add `--scope user` to reach it from every project
instead.

Then run `/mcp` inside Claude Code and authenticate. Claude Code opens your browser for the consent
screen.

## ChatGPT

1. Open ChatGPT, then **Settings > Apps & Connectors**.
2. Choose **Create**.
3. Fill in **Name** (`pylo`), **Description**, and **MCP Server URL**
   (`https://<your-pylo-mcp-host>/mcp/<customer-id>`).
4. Set **Authentication** to **OAuth**.
5. Read the warning, tick the box, then create the connector.

> **Create is hidden**
> ChatGPT shows **Create** only in developer mode. Turn it on under **Settings > Apps & Connectors >
> Advanced settings**, then reopen the connectors list.

ChatGPT warns about every custom connector, because it cannot vet what a third-party server does
with your data. The grant Pylo asks for is read-only.

## Codex

```bash filename="terminal"
codex mcp add pylo --url https://<your-pylo-mcp-host>/mcp/<customer-id> --oauth-resource https://<your-pylo-mcp-host>/mcp/<customer-id>
codex mcp login pylo
```

`codex mcp login` opens the browser for the consent screen. `--oauth-resource` has to repeat the
endpoint: Codex uses it as the OAuth resource indicator, and it is not inferred from `--url`.

## Cursor

```json filename=".cursor/mcp.json"
{
  "mcpServers": {
    "pylo": {
      "url": "https://<your-pylo-mcp-host>/mcp/<customer-id>"
    }
  }
}
```

Use `~/.cursor/mcp.json` instead to reach Pylo from every project. Then open **Settings > MCP** and
log in to Pylo on the new server.

## VS Code

```json filename=".vscode/mcp.json"
{
  "servers": {
    "pylo": {
      "type": "http",
      "url": "https://<your-pylo-mcp-host>/mcp/<customer-id>"
    }
  }
}
```

Run **MCP: List Servers** from the command palette, start Pylo, then log in. Pylo's tools appear in
Copilot Chat's agent mode, not in ask mode.

## Gemini

```json filename="~/.gemini/settings.json"
{
  "mcpServers": {
    "pylo": {
      "httpUrl": "https://<your-pylo-mcp-host>/mcp/<customer-id>"
    }
  }
}
```

The key is `httpUrl`, not `url`. Restart the Gemini CLI, then run `/mcp auth` to approve Pylo.

## Any other MCP client

Register a remote server over streamable HTTP with the same endpoint. Pylo implements OAuth 2.1 with
dynamic client registration, so the client obtains its own credentials and needs no ID or secret
from you.

| Setting        | Value                                            |
| -------------- | ------------------------------------------------ |
| Name           | `pylo`                                           |
| Server URL     | `https://<your-pylo-mcp-host>/mcp/<customer-id>` |
| Transport      | Streamable HTTP                                  |
| Authentication | OAuth 2.1                                        |

## Troubleshooting

| Symptom                                   | Cause                                                                                 |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| 404 from the MCP server                   | The customer id in the URL is not a valid UUID                                        |
| OAuth fails with `invalid_target`         | The id is a well-formed UUID, but no such customer exists                             |
| The client rejects the connector name     | Claude Code allows only `[A-Za-z0-9_-]`. Drop spaces and punctuation                  |
| The agent connects but finds no tools     | The connector is added but not enabled for the conversation                           |
| The agent cannot see an entity you expect | Grants inherit your Pylo permissions. The agent reads exactly what your user may read |

## After connecting

[Settings > Connect Pylo](https://app.pyloapp.com/p/settings/connected-apps) lists every app you
have authorized, with the host it connects from, when you connected it, and when it last called the
API. Revoke access there. The app loses access immediately and has to run the handshake again to
reconnect.