Connect your clientCopy Anchor Link

Choose the client or model gateway that will call RunHarvester. Configure the same endpoint twice when the agent needs both Data and Browser Workflow tools.

[mcp_servers.runharvester_data]
url = "https://api.runharvester.com/mcp"
bearer_token_env_var = "RUNHARVESTER_DATA_API_KEY"
default_tools_approval_mode = "writes"
tool_timeout_sec = 45

[mcp_servers.runharvester_browser]
url = "https://api.runharvester.com/mcp"
bearer_token_env_var = "RUNHARVESTER_BROWSER_API_KEY"
default_tools_approval_mode = "writes"
tool_timeout_sec = 45

Authentication and tool visibilityCopy Anchor Link

Send one existing RunHarvester key in either header:

Authorization: Bearer rh_live_...

X-API-Key: rh_live_...

If both headers are present, their values must be identical. Keys in the URL or query string are not accepted.

The key type controls the API family exposed to the agent:

tools/list includes only operations granted by the current key scopes. Every tool call resolves the key and checks its scope again, so revocation, expiry, and permission changes take effect without reconnecting.

To use both API families, configure the same /mcp URL twice under different names and use a Data key for one connection and a Browser Workflow key for the other.

ToolsCopy Anchor Link

The MCP server provides 28 RunHarvester API operations, plus connection-aware helpers. MCP clients can inspect the complete input schema for every available tool through tools/list.

Tool inputs follow the public RunHarvester API schemas. Path, query, and allowed header parameters are top-level snake_case fields, while JSON bodies remain under body. Browser project_id and environment_id are taken from the API key binding and cannot be overridden by the agent.

workflow_create_batch_manifest accepts typed admission fields and an items array. MCP clients can inspect the complete input schema for every available tool through tools/list.

Response envelopesCopy Anchor Link

All successful tool calls return:

{ "ok": true, "status": 200, "data": {}, "meta": {} }

API errors set MCP isError and return a safe envelope:

{
  "ok": false,
  "status": 429,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded",
    "request_id": "..."
  },
  "retry_after": "1"
}

Only request ID, credit, rate-limit/retry, and route metadata headers can appear in meta.

Resources and bounded contentCopy Anchor Link

The server provides these resources or resource templates:

runharvester://contract/openapi
runharvester://data/requests/{id}/result/{part}
runharvester://browser/runs/{runId}/evidence/{evidenceId}/{expiresAt}/{signature}

data_get_result returns metadata and UTF-8 previews up to 4 KiB. Read retained html, text, data, or the full result with data_read_result_content: the default chunk is 16 KiB and the maximum is 64 KiB. Its opaque cursor is bound to the request and content part.

Screenshot evidence is MCP image content; masked HTML is text content. Existing signed-resource expiry and the 1 MiB screenshot limit remain enforced by the REST implementation.

Wait helpers poll once per second, default to 10 seconds, and accept at most 30 seconds. A non-terminal timeout is successful and includes timed_out: true plus retry_after_ms; MCP cancellation aborts the wait.

The MCP request body limit is 4 MiB. Manifests that exceed it must be uploaded through the REST API or SDK.

Verify the connectionCopy Anchor Link

After adding the MCP server, verify that the client can see it and ask the agent to call connection_info.

For Codex, run:

codex mcp list

You can also use /mcp in Codex to view connected servers and their available tools.

connection_info returns the API key type and granted scopes. For a Browser Workflow key, it also returns the bound workspace, project, and environment. The API key itself is never returned.

If an expected tool is missing, check that the connection uses the correct key type and that the key has the required scope.

Keep credentials safeCopy Anchor Link

• Store API keys in environment variables or your MCP client's secret storage.
• Do not put a key in the MCP URL or query string.
• Do not commit a literal key to a configuration file.
• Treat signed Browser Workflow evidence URLs as temporary secrets.