Hosted MCP

Gradient hosts a remote Model Context Protocol server on the console. Point an MCP client at it with an organization API key and a coding agent can build agents, deploy and call tools, manage knowledge bases and phone numbers, run dataset SQL, and author red-team and rubric experiments, the same operations the dashboard exposes.

https://console.usegradient.dev/api/mcp

The transport is Streamable HTTP. The server exposes tools (no separate resources).

Connecting

Authenticate with Authorization: Bearer grad_live_..., an organization API key from the console. The server verifies the key, then enforces the matching scope on each tool it runs, so a key scoped to agents:* and tools:* can build and deploy but not, say, manage providers. See Authentication for scopes.

Streamable HTTP
stdio (mcp-remote)

For clients that speak Streamable HTTP directly, such as Claude Code and Cursor:

{
  "mcpServers": {
    "gradient": {
      "url": "https://console.usegradient.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer grad_live_..."
      }
    }
  }
}

For stdio-only clients, proxy through mcp-remote:

{
  "mcpServers": {
    "gradient": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://console.usegradient.dev/api/mcp",
        "--header",
        "Authorization: Bearer ${GRADIENT_API_KEY}"
      ],
      "env": {
        "GRADIENT_API_KEY": "grad_live_..."
      }
    }
  }
}

Tool surface

Identity

Tool	Does
`whoami`	Return the authenticated organization and key scopes.

Agents

Tool	Does
`list_agents`	List agents in the organization.
`create_agent`	Create an agent with a draft start node.
`get_agent`	Read builder state: topology, history, published versions.
`update_agent`	Update an agent’s name, description, or greeting.
`delete_agent`	Delete an agent and its traces, and release attached phone numbers.
`get_agent_builder`	Load the mutable draft builder state.

Graph editing

Each of these acts on an agent’s draft graph.

Tool	Does
`add_node`	Add a draft node; `kind` selects the block (subagent, function, logic_split, agent_transfer, code, and others).
`update_node`	Update a node’s label, description, prompt, model, or config.
`delete_node`	Delete a non-entrypoint node.
`add_connection`	Add an `agent_swap` handoff edge between two nodes.
`delete_connection`	Remove a handoff edge.
`add_tool_to_node`	Attach a deployed custom tool to a node.
`remove_tool_from_node`	Remove a custom or knowledge-base tool from a node.
`attach_skill`, `detach_skill`	Attach or detach an organization skill.
`add_knowledge_base_to_node`	Attach a knowledge base search tool.
`restore_node`	Restore one node in the draft from a published version.
`restore_version`	Restore the whole draft graph from a published version.

Publish and run

Tool	Does
`publish_agent`	Publish the reachable draft as the next immutable version.
`chat_agent`	Run the latest published agent to completion.
`start_agent_run`	Start a durable run that drives until it ends or waits.
`list_agent_runs`	List recent durable runs for an agent.
`get_agent_run`	Get a durable run and its transcript.
`new_conversation`	Start a fresh published conversation transcript.

Skills

Tool	Does
`list_skills`, `get_skill`	List and read organization skills.
`create_skill`, `update_skill`, `delete_skill`	Manage skills.

Knowledge bases

Tool	Does
`list_knowledge_bases`, `get_knowledge_base`	List and read knowledge bases.
`create_knowledge_base`, `update_knowledge_base`, `delete_knowledge_base`	Manage knowledge bases.
`list_kb_documents`, `ingest_kb_document`	List documents and ingest plain text.
`search_kb`	Semantic search over a knowledge base.

Custom tools

Tool	Does
`list_tools`, `get_tool`	List and read organization tools.
`create_tool`, `update_tool`, `delete_tool`	Manage tool handlers and schemas.
`test_tool`	Invoke a deployed tool by id or slug for testing.
`invoke_tool`	Invoke a deployed tool by slug via the public invoke API.

Providers

Tool	Does
`list_providers`, `list_models`	List provider connections and available models.
`set_provider_key`, `delete_provider_key`	Manage BYOK provider API keys.

Phone and voice

Tool	Does
`list_phone_numbers`, `search_phone_numbers`	List purchased numbers and search inventory by area code.
`buy_phone_number`, `update_phone_number`, `release_phone_number`	Buy, reassign or pin, and release voice numbers.
`create_outbound_call`	Place an outbound voice call that runs an agent graph.

Dataset worlds

Tool	Does
`list_dataset_databases`, `create_dataset_database`	List and create Postgres dataset worlds.
`list_dataset_tables`, `create_dataset_table`	List and create tables.
`list_dataset_rows`, `insert_dataset_row`	Read and insert rows.
`run_dataset_sql`, `get_dataset_schema`	Run SQL and introspect the schema.
`create_dataset_snapshot`	Pin a snapshot at a point in the dataset’s history.
`acquire_dataset_fork`, `release_dataset_fork`	Fork a world for an isolated conversation, then release it.

Evaluation and observability

Tool	Does
`list_runs`, `get_run`	List and read trace runs.
`list_datasets`, `create_dataset`	List and create evaluation datasets.
`list_experiments`, `create_experiment`	List and create red-team scenarios or QA rubrics against an agent.
`run_red_team_experiment`	Run an engine-backed red-team experiment.
`delete_experiment`	Delete an experiment with its runs and results.

Each tool returns its result as JSON text; very large payloads are truncated with the original size noted. For how these operations fit the build-and-evaluate loop, see Run over MCP.

Overview

Agents

Tools

MCP

Connecting

Tool surface

Identity

Agents

Graph editing

Publish and run

Skills

Knowledge bases

Custom tools

Providers

Phone and voice

Dataset worlds

Evaluation and observability

​Connecting

​Tool surface

​Identity

​Agents

​Graph editing

​Publish and run

​Skills

​Knowledge bases

​Custom tools

​Providers

​Phone and voice

​Dataset worlds

​Evaluation and observability

Connecting

Tool surface

Identity

Agents

Graph editing

Publish and run

Skills

Knowledge bases

Custom tools

Providers

Phone and voice

Dataset worlds

Evaluation and observability