Guidelines for MCP servers
A tool pack’s MCP server is spoken to by Jacker, not by the agent. Jacker starts the server, lists its tools, and calls them on the agent’s behalf, on every engine. This page says what that means for the server you write.
How Jacker talks to your server
- Jacker is an MCP client that advertises no capabilities. Requests for sampling, elicitation, or roots aren’t answered; don’t depend on them.
- Jacker reads
tools/listand callstools/call. Resources and prompts aren’t used. - A
stdioserver runs in the user’s project folder, inside the sandbox. See What a plugin’s programs can reach. - An
httpserver is reached over the streamable HTTP transport at the manifest’surl, with the manifest’sheaders. - Jacker starts one server for each project folder that uses it, so a work-item branch in its own folder gets its own server. It stops a server after 10 minutes without use, and runs at most 8 at a time.
Names and descriptions
Agents see your tools as plug_PUBLISHER_NAME_TOOL, with every character that isn’t a letter, digit, or underscore replaced by _. Names over 64 characters are shortened with a hash. Users see Display name ▸ tool.
The description starts with [Plugin: DISPLAY_NAME]. Write the rest for the agent: what the tool does, when to use it, and what it returns.
Limits
Jacker applies the following limits to each server:
| Limit | Value | When it’s exceeded |
|---|---|---|
| Tools | 40 | Tools after the 40th are left out. |
| Description | 1,024 characters | The rest is cut. |
| Input schema | 8 KB of JSON | The tool is left out. |
| Call time | 60 seconds, or the manifest’s timeoutMs | The call fails. |
| Result text | 100,000 characters | The text is cut, with a note. |
| Start time | 5 seconds | That run goes without the server; the next run has it. |
Failures
- A call that fails or times out reaches the agent as a tool error. It doesn’t stop the run.
- After 5 failed calls in a row, Jacker rests the server for a minute and answers its calls with an error at once.
- If the server exits 3 times within 5 minutes, Jacker stops using it until Jacker restarts.
Results
Return text and image content. Other content kinds reach the agent as a note that a result was left out. A result with isError: true reaches the agent as an error.
Jacker marks every result as output from a plugin, to be treated as data. Don’t put instructions to the agent in results.
Read-only tools
List every tool that changes nothing in readOnlyTools. A plan-mode run can use only those, and only after the user has approved them for the project. Jacker doesn’t trust a tool’s own readOnlyHint for this.
Permission
Users approve each tool on its first use in a project; they can choose not to be asked again. A run that can’t ask the user (a work-item stage, for example) is offered only tools approved earlier. Keep each tool’s purpose narrow, so approving one says what it does.
Secrets
Declare a token as a config value with "secret": true, and pass it to your server through env or headers. Don’t ship a key in the plugin; the marketplace refuses archives that contain one.