Skip to content
Ctrl/⌘ K

MCP

MCP run agent tool

Run a light or deep agent with an allowlisted model and stored BYOK key.

Overview

Run a light or deep agent with an allowlisted model and the account's stored provider key.

Use the typed search tools for web retrieval. Use list_models before BYOK query-builder or agent calls, and configure a provider key at the returned setup_url when requested. When a tool error's structured content includes error.validation, correct every listed RFC 6901 issue before retrying and never repeat an unchanged rejected input.

Input schema

MCP run agent tool input
Name
mode
Required
Yes
Type
AgentEntrypoint
Description
Execution depth for this run.
Constraints
Name
input
Required
Yes
Type
string
Description
Research request passed to the selected agent program.
Constraints
min length: 1; max length: 20000
Name
model
Required
Yes
Type
AgentModelRef
Description
Exact allowlisted provider/model pair selected for this run.
Constraints
Name
background
Required
No
Type
boolean
Description
Return immediately with polling credentials instead of awaiting the result.
Constraints
default: false

Output schema

Returns structured JSON from the shared public API service.

Tool errors

Tool execution failures set isError to true. When error.validation is present, correct every RFC 6901 issue before retrying and do not repeat unchanged input.

Request json 
{
  "error": {
    "code": "invalid_request",
    "reason": "malformed_request",
    "message": "invalid request: request body violates the public contract",
    "recovery": null,
    "agent_session_id": null,
    "validation": {
      "contract": "SearchPostRequest",
      "issues": [
        {
          "code": "required",
          "path": "/query",
          "suggestion": "Add the required `query` field."
        }
      ],
      "truncated": false
    }
  },
  "request_id": "00000000-0000-0000-0000-000000000000"
}

Behavior

This tool is state-changing or billable, non-destructive, and not idempotent.

Commands