Docs / Agents and API

MCP server

A remote MCP server that gives any MCP client the Volley tools.

On this page

Connect a client
How it works
Tools
Resources
Example prompts
Calling it by hand

Volley runs a remote Model Context Protocol server at https://volley.sh/mcp. Connect any MCP client to it and your agent can check, describe, render, verify and save diagrams, and read your diagrams and collections as context.

Connect a client

You need an API key.

Claude Code

bash

claude mcp add --transport http volley https://volley.sh/mcp \
  --header "Authorization: Bearer $VOLLEY_KEY"

Clients with a JSON config

Most clients that support remote servers take a URL and headers. In Cursor's mcp.json, for example:

json

{
  "mcpServers": {
    "volley": {
      "url": "https://volley.sh/mcp",
      "headers": { "Authorization": "Bearer volley_..." }
    }
  }
}

Clients that can only start local servers can reach Volley through a bridge such as mcp-remote, passing the same header.

Volley is listed in the MCP Registry as sh.volley/volley.

How it works

Transport is Streamable HTTP with JSON responses, protocol version 2025-06-18. The server answers POST only and does not open an event stream.
Each request carries one JSON-RPC message.
Calling a tool or reading a resource counts as one API call. Listing tools and resources is free. See Usage and limits.
The server's instructions include a short primer on the syntax, so the agent can start writing without reading these docs.

Tools

Tools that work on a diagram take either source, the diagram text, or id, the id of one of your saved diagrams.

Tool	Arguments	Returns
`check_diagram`	`source` or `id`	Each error and warning with line and column, or `ok` with a count of lanes, messages and payloads
`describe_diagram`	`source` or `id`	The diagram as Markdown: lanes, numbered messages, replies, notes, sections and every payload
`render_svg`	`source` or `id`, `theme` (`light` or `dark`), `showPayloads`	SVG markup
`verify_diagram`	`source` or `id`, `har` (the HAR file's text or parsed JSON)	A drift check report
`list_diagrams`	`query`, `limit` (up to 100), `cursor`	Your saved diagrams with ids, titles, visibility and links, a page at a time
`get_diagram`	`id`	A saved diagram's title, visibility, short link and full source
`save_diagram`	`source`, optional `id` to update, `visibility`	The short link, a README embed and a check summary
`list_collections`	`query`	Your collections with ids and scenario counts
`get_collection`	`id`, `full`	The scenarios in a collection, or with `full: true` the whole collection as Markdown
`save_collection`	`title`, optional `id`, `description`, `visibility`, `entries`	The saved collection. `entries` replaces the whole list. Pro only.
`add_to_collection`	`collectionId`, `diagramId`, `scenario`, `note`	Adds a diagram to a collection, or updates its entry. Pro only.

save_diagram follows your plan: Free accounts can hold one saved diagram, private diagrams are Pro only, and on Pro, updating a diagram keeps the previous source as a version.

Errors from a tool, such as a missing diagram or a plan limit, come back as a tool result marked as an error, with a message the agent can act on.

Resources

The server exposes your saved work as Markdown resources, so a client can attach them as context:

Resource	Contents
`volley://collection/{id}`	The whole collection: introduction, then each scenario with its note and the full description of its diagram
`volley://diagram/{id}`	The diagram's description, its link and its source

Resources include private diagrams and collections, because the key proves they are yours.

Example prompts

"Draw the sequence of calls in src/payments/checkout.ts as a Volley diagram with the request and response bodies, check it, and save it."
"Read the Volley collection for our billing integration and tell me which scenario covers a partial refund."
"Verify docs/checkout.volley against test-results/checkout.har and fix any steps that drifted."

Calling it by hand

bash

curl -s https://volley.sh/mcp \
  -H "Authorization: Bearer $VOLLEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_diagram","arguments":{"source":"A -> B: hi"}}}'

`/` or `Ctrl`+`K`	Search the docs
`↑` `↓`	Move through search results
`Enter`	Open the highlighted result
`Ctrl`+`Enter`	Open the result in a new tab
`[` and `]`	Previous and next page
`g` then `h`	Docs home
`t`	Back to the top of the page
`?`	Show these shortcuts
`Esc`	Close a dialog

MCP server

#Connect a client

#Claude Code

#Clients with a JSON config

#How it works

#Tools

#Resources

#Example prompts

#Calling it by hand