Connect a client

Any client needs two things: that URL, and a token. Clients that support OAuth can discover the authorization server themselves; the rest take an API key as a Bearer header. Use a read_write token if the assistant should be able to save or edit references — a read-only token can still browse, but every writing tool will fail.

Claude Code

# OAuth — opens a browser to authorize
claude mcp add --transport http paperpile https://stage-mcp.paperpile.com
claude mcp login paperpile

# …or authenticate with an API key instead
claude mcp add --transport http paperpile https://stage-mcp.paperpile.com \
  --header "Authorization: Bearer YOUR_API_KEY"

The server is added to the current project only. Pass --scope user to make it available everywhere. On a headless or SSH session, claude mcp login paperpile --no-browser prints the authorization URL instead of opening a browser. Verify with claude mcp list, and remove it with claude mcp remove paperpile.

Claude Desktop

Remote servers are added through Connectors, not claude_desktop_config.json — that file is for local stdio servers.

Open Settings (Ctrl+, on desktop, ⌘⇧, in the browser) and choose Connectors.
Click Add, then Add custom connector.
Paste https://stage-mcp.paperpile.com and click Add.
Complete the authentication prompt.

Once connected, you can enable or disable individual tools from the connector's settings.

Codex CLI

Remote servers are configured in ~/.codex/config.toml, or in .codex/config.toml to scope them to one project. codex mcp add only handles stdio servers, so add the entry by hand:

[mcp_servers.paperpile]
url = "https://stage-mcp.paperpile.com"
bearer_token_env_var = "PAPERPILE_API_KEY"

bearer_token_env_var names the environment variable holding your token; Codex sends its value as the Authorization bearer token. Omit it to use OAuth instead, which is the default. http_headers sets static headers if you need them.

Antigravity

Remote servers are configured in ~/.gemini/config/mcp_config.json, or in .agents/mcp_config.json to scope them to one workspace:

{
  "mcpServers": {
    "paperpile": {
      "serverUrl": "https://stage-mcp.paperpile.com",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

To use OAuth instead, drop the headers block entirely — Paperpile's authorization server supports dynamic client registration, which Antigravity handles on its own. Then open settings (Cmd/Ctrl+,), go to the Customizations tab, click Authenticate next to the server, and paste the authorization code back into the settings panel.

Any other client

Point it at https://stage-mcp.paperpile.com as a Streamable HTTP server and give it either an API key as Authorization: Bearer …, or let it run the OAuth flow — it can discover the authorization server from /.well-known/oauth-protected-resource.