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

# Hosted MCP

> Connect Claude Code, Cursor, or any MCP client to Gradient's hosted Streamable HTTP server to drive your organization by API key.

Gradient hosts a remote [Model Context Protocol](/run/mcp) 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.

```text theme={null}
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](/api/authentication) for scopes.

<Tabs>
  <Tab title="Streamable HTTP">
    For clients that speak Streamable HTTP directly, such as Claude Code and Cursor:

    ```json theme={null}
    {
      "mcpServers": {
        "gradient": {
          "url": "https://console.usegradient.dev/api/mcp",
          "headers": {
            "Authorization": "Bearer grad_live_..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="stdio (mcp-remote)">
    For stdio-only clients, proxy through `mcp-remote`:

    ```json theme={null}
    {
      "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_..."
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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](/run/mcp).