Plugins and connectors

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

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.

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:

{
  "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 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.

{ "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

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.