# Plugins and connectors

> Give the agent tools from other services and programs. How to add one, how to write one, and the manifest format.

Source: https://graspable.dev/docs/plugins

A plugin gives the agent more tools. A **connector** is a plugin whose tools reach another service, for example a 3D model generator or your team's tracker. Plugins work with every AI choice: the Graspable agent, Claude Code and Codex get the same tools.

Plugins work for projects on your computer. Cloud projects do not use them yet.

## Add one

Open **Settings → Plugins and connectors**.

- **Switch on a connector that comes with Graspable.** Tick it, fill in what it asks for and choose **Save**. Then choose **Test**: it connects once and tells you how many tools it found.
- **Add an MCP server.** Open **Add a plugin or an MCP server**, give it a name and its `https` address, and tick **needs an access token** if it does. Any service with an MCP server works this way.
- **Add a plugin.** Paste the path of its folder on your computer, or the `https` address of its manifest.

Secret values such as API keys are kept in your computer's keychain. They are handed to a run when it starts and are never written to a file by Graspable.

## What the agent may do with them

Every plugin tool counts as reaching outside your project. With the default approval setting the agent asks you before it uses one. A plugin can mark a tool as read-only; those run without asking. See [Approvals and safety](https://graspable.dev/docs/approvals-and-safety.md).

The tools appear in a run's **Context** list under **Plugins**, together with any plugin that could not connect and why.

## Pipedream

The **Pipedream** connector gives the agent tools for thousands of services through your own Pipedream project. You need a Pipedream account, a project, and its client ID and secret. List the apps you want, separated by commas, for example `notion, slack`. The first time a tool needs an account, the agent shows you a link to connect it.

## Write a plugin

A plugin is a folder with a file named `graspable-plugin.json`:

```json
{
  "name": "meshes",
  "title": "Meshes",
  "version": "1.0.0",
  "kind": "connector",
  "description": "Generate 3D models from a description.",
  "fields": [
    { "name": "API_KEY", "label": "API key", "secret": true, "url": "https://example.com/keys" }
  ],
  "mcp": {
    "type": "http",
    "url": "https://mcp.example.com/v1",
    "headers": { "Authorization": "Bearer ${API_KEY}" }
  },
  "risk": { "search_models": "read" }
}
```

| Key | Meaning |
|---|---|
| `name` | Lowercase letters, digits and dashes. Tools are offered as `<name>__<tool>`. |
| `kind` | `plugin` or `connector`. |
| `fields` | What the person fills in. `secret: true` goes to the keychain. `default` and `optional` are allowed. |
| `mcp` | Where the tools come from. `${NAME}` is replaced with a field's value. |
| `risk` | What a tool can do: `read`, `write`, `exec` or `external`. Tools not listed are `external` and ask first. |
| `skills` | A folder of [skills](https://graspable.dev/docs/skills.md) the plugin brings. Default: `skills`. |

The `mcp` part has two forms.

**An address.** `type: "http"` with an `https` `url` and optional `headers`. Two extras:

- `oauth`: `{ "tokenUrl", "clientId", "clientSecret" }` gets a bearer token with the client-credentials flow before connecting.
- `each`: `{ "name": "APP", "from": "APPS" }` opens one connection for every comma-separated item of the field `APPS`, with the item available as `${APP}`.

**A program.** `type: "stdio"` with a `command`, `args` and `env`. Graspable starts it in the plugin's folder and talks MCP over its standard input and output. `node`, `npx` and `bun` work even when Node.js is not installed, because Graspable's built-in runtime answers to those names.

```json
{ "mcp": { "type": "stdio", "command": "node", "args": ["server.js"], "env": { "API_KEY": "${API_KEY}" } } }
```

A plugin that starts a program must be added from a folder on your computer. A manifest added from an address may only point at an MCP address.

## From a terminal

```bash
grasp plugins
grasp plugins add ./meshes
grasp plugins on meshes
```

For a run started with `grasp run`, secret fields come from the environment: `GRASPABLE_PLUGIN_<NAME>_<FIELD>`, for example `GRASPABLE_PLUGIN_MESHES_API_KEY`. See [The grasp command](https://graspable.dev/docs/cli.md).