Skip to main content

Connect an MCP Client

The SmartHopper MCP Server component lets external Model Context Protocol clients — such as Claude Desktop, Cursor, VS Code, Claude Code, or your own scripts — inspect and work with your live Grasshopper session.

1. Start the server in Grasshopper​

  1. Drop the SmartHopper MCP Server (MCP) component from SmartHopper → A. AI onto your canvas.
  2. (Recommended) Wire a secret string into Bearer Token (T).
  3. Set Enable (E) to True. The Url (U) output displays your endpoint (http://127.0.0.1:26929/mcp by default).

Choosing which capabilities to unlock​

By default, the server binds to loopback (127.0.0.1) and exposes only local, read-only canvas and GhJSON tools. Flip the optional boolean inputs on the component to unlock additional capabilities when your workflow needs them:

  • Allow Editing (AE) — exposes tools that place, wire, move, group, or edit components and scripts on the canvas. Every edit still opens the review dialog unless you also set Auto-approve changes (AA) to True.
  • Allow View Control (AV) — exposes viewport navigation (canvas_view).
  • Allow External Tools (ET) — exposes tools that read local files (file2md), capture screenshots, fetch web/forum URLs (web2md, Discourse), or call your configured AI providers.

See the full parameter table on MCP Server Component.

2. Configure your MCP client​

Point any HTTP-capable MCP client to the Url output and pass the Authorization header if you set a Bearer Token:

{
"mcpServers": {
"smarthopper": {
"url": "http://127.0.0.1:26929/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}

3. What your MCP client gets​

  • Tools — all enabled tools from the AI Tools Library, filtered by the permissions you enabled on the component.
  • Embedded documentation (docs:///) — built-in reference guides including the GhJSON and GhPatch specifications, Grasshopper scripting guides, and canonical workflows.
  • Reusable prompts (prompts:///) — ready-made system prompts (such as grasshopper-expert and definition-builder) that teach external coding agents how to work with Grasshopper and GhJSON.