# The Graspable MCP server

> Let another AI agent build with Graspable. Set-up for Claude Code, Codex and other MCP clients, and the list of tools.

Source: https://graspable.dev/docs/mcp-server

Graspable has an MCP server. With it, another AI agent can create projects, ask Graspable's agent to build, follow the run, read and write files, check the result and start the preview.

## Set it up

First install `grasp` and sign in once with `grasp login`: [The grasp command](https://graspable.dev/docs/cli.md).

**Claude Code**

```bash
claude mcp add graspable -- grasp mcp
```

**Codex**

```bash
codex mcp add graspable -- grasp mcp
```

**Any other MCP client** that starts a program:

```json
{ "mcpServers": { "graspable": { "command": "grasp", "args": ["mcp"] } } }
```

**Over HTTP.** The same server is at `POST /mcp` of the [local API](https://graspable.dev/docs/api.md), with an access token:

```json
{ "mcpServers": { "graspable": { "type": "http", "url": "http://127.0.0.1:<port>/mcp", "headers": { "Authorization": "Bearer <token>" } } } }
```

## Tools

| Tool | What it does |
|---|---|
| `list_templates` | The project templates |
| `list_projects` | The person's projects |
| `create_project` | Create a project from a template |
| `list_files`, `read_file`, `write_file` | Work with a project's files |
| `start_run` | Ask Graspable's agent to build or change something, in plain words |
| `get_run` | What a run has done so far. Waits for it to finish or to need an answer |
| `approve` | Answer a run's approval request |
| `cancel_run` | Stop a run |
| `list_runs` | Earlier runs of a project |
| `check_project` | Build the project and load it in a headless browser |
| `start_preview` | Start the live preview and return its address |

## The usual flow

1. `create_project`, or `list_projects` to find one.
2. `start_run` with the request. It returns a run id at once.
3. `get_run` with that id until the state is `completed`, `failed` or `cancelled`. Pass the `since` number from the last answer to get only what is new.
4. When `get_run` lists `needs_approval`, call `approve`.
5. `start_preview` to look at the result.

A run completes only when the project builds and loads in a browser. A failed check goes back to Graspable's agent, up to three times, before the run fails.

## What the other agent may do

`grasp mcp` acts with the **run** level of access: it can create projects, edit files, start runs and answer approvals. It cannot change plugins, sign-ins or settings, and it cannot delete projects.

Approval requests exist so that a person decides. An agent that calls `approve` decides in your place. If you do not want that, tell the agent to stop and ask you when a run needs an approval, or start runs with the `strict` policy and answer in the app.