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

# Connect to Pomerado

Add your Pomerado MCP endpoint to a client that supports remote Streamable HTTP and OAuth. Use the exact URL supplied for your account or integration.

## Choose an endpoint

| Endpoint | Use it to | Where to get the URL |
| - | - | - |
| Account MCP | Find public tools, build tools, run operations and manage saved logins when available | Use the account MCP URL supplied by Pomerado |
| Individual integration | Use the generated tools in one integration | Open the integration in the Dashboard and copy the URL under **MCP endpoint** |

* Choose an individual integration for a client that needs only that integration's tools.
* Choose the account MCP endpoint to discover or create operations across websites.
* Keep the exact URL supplied for your chosen integration. Public and private integrations for the same website have different URLs.
* Wait for a URL when the Dashboard shows endpoint registration as queued or in progress. A pending, disabled or failed endpoint is not ready to connect.

Individual integration URLs use `/mcp/integrations/{integration_id}` on the supplied MCP host. The integration ID is a UUID. The account MCP URL is deployment-specific. The service also calls this the admin endpoint.

## Connect your client

1. Open your client's settings for remote MCP servers.
2. Add the complete MCP endpoint URL with Streamable HTTP transport.
3. Follow the client's OAuth sign-in and consent flow for Pomerado.
4. Refresh the client's available tools after authentication succeeds.

Pomerado checks account access automatically after OAuth consent. There is no second Pomerado approval step for the MCP connection.

Your client sends MCP requests directly to the backend endpoint. The Dashboard helps you find integrations and manage your account. It does not relay the client's MCP calls.

## Discover tools

Use your client's tool list to inspect the available names, descriptions and input schemas. Integration endpoints advertise generated tool names for their own operations. The account MCP endpoint advertises `find_tool`, `build_tool` and `run_tool`.

For client developers, this is a JSON-RPC tool-list request after the client completes MCP initialization and authentication.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

On the account MCP endpoint, this read-only call finds public operation definitions.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "find_tool",
    "arguments": {
      "limit": 10
    }
  }
}
```

These examples are message bodies for an authenticated MCP client. Let the client handle transport headers and the protocol handshake.

## Run an operation

* Inspect the discovered tool's input schema and whether it reads or changes the website.
* Submit arguments that match the schema in the [tool reference](tool-reference.md).
* Follow a returned job ID with `get_job` and `wait_seconds`, as the result's `next` says, until it completes or needs input.
* Open the supplied protected form when a job needs website credentials.
* Check the website before repeating an action whose outcome is uncertain.

`build_tool` works on the real website as part of the build:

* A read build runs your example to prove the tool.
* A write build performs the change you requested once, with your input, and publishes the tool without running it again. The change may have happened even when publication fails.

## Keep your agent waiting on jobs

A job that asks a question waits at most 10 minutes for the answer, then fails. Your agent learns about a question only while one of its calls is open, so it follows each job with a long `get_job` wait ([jobs](jobs.md#wait-for-a-job)). The server's MCP instructions and each result's `next` tell the agent to do this; the client settings below let the wait last.

**Claude Code**

* Add the server with `claude mcp add --transport http pomerado <url>`, then sign in. No other setup is needed.
* After a build or run, Claude calls `get_job` with a long wait. After 2 minutes Claude Code moves the call to the background (it shows in `/tasks`) and Claude keeps working. When the job asks or finishes, the call returns as a task notification. Claude Code documents that such a result starts a new turn even from an idle session; Pomerado has not yet verified that wake in an interactive session.
* A wait also returns shortly before your access token expires (about every 5 minutes today), with the job still running and `next` saying to wait again.
* Keep the session open while a job runs: background calls end when Claude Code exits.
* Leave `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` unset (0 turns backgrounding off), and don't set `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` below 60 seconds. Progress every 15 seconds keeps the call from going idle.
* Claude Code declares MCP elicitation, so it is expected to show a plain question as a dialog and to open the protected page for a code or a login. Pomerado has tested this with the MCP SDK's client, not yet in Claude Code itself.
* Headless `claude -p`: the wait blocks the run until the job asks or finishes, which is what an unattended run needs. Don't set `CLAUDE_AUTO_BACKGROUND_TASKS=1` for Pomerado runs: the call moves to the background, the run ends its turn and the process then stops the call. A headless run cancels dialogs, so the question comes back to the agent with `next`.
* If something prevents long calls, loop a short check: `/loop 2m check Pomerado job <id> with get_job and relay any pending question`.
* Claude Code's Monitor tool and plugin monitors watch shell commands, and Pomerado offers no command-line watch for a job. Use the held wait above.

**Other clients**

| Client | Setting |
| - | - |
| Codex CLI | `tool_timeout_sec = 1800` under `[mcp_servers.pomerado]` (the default cuts calls at 300 s) |
| Cursor (editor) | None; its tool-call limit (about an hour) covers a 30-minute wait |
| Cursor CLI | None available; calls stop at 60 s, so the agent loops `wait_seconds` of 50 |
| VS Code with Copilot | None; it sets no MCP call timeout |
| OpenCode | Leave `timeout` unset; progress keeps the call alive, and the value would cap tool calls |
| Gemini CLI | The server's `timeout` to `600000` (ms, its maximum) |
| Zed | `context_server_timeout` to `600` (seconds, its maximum) |
| Cline | The server's `timeout` to `1800` |
| Goose | Raise the extension's `timeout` |
| claude.ai, Claude Desktop, ChatGPT | None available; the agent loops short waits while the chat is active |

A client whose calls time out sooner than the wait gets the job back sooner only if the agent asks for less: `next` says to pass a `wait_seconds` below the client's timeout and call again while the job runs.

Read [authentication](authentication.md) for connection failures, [jobs](jobs.md) for job progress and [saved logins](connections.md) for website access.


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