Immutable. This exact content is served forever at /api/v1/blob/d8482a37f8b15908.
---
name: authoring
description: Add or edit an MCP server entry in mcptoon's config correctly — stdio/streamable-http/sse shapes, command rules, placeholders, and validation.
---
# Author an MCP server entry for mcptoon
All servers live in `~/.mcptoon/config.json` under `mcpServers`. Edit there,
never in agent-side files, then run `mcptoon sync`.
## Entry shapes
stdio (local process):
```json
{
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
"env": {"NODE_ENV": "production"}
}
}
```
streamable-http / sse (remote):
```json
{
"remote-tools": {
"type": "streamable-http",
"url": "https://example.com/mcp"
}
}
```
## Hard rules for stdio commands
- `command` is ONE executable token: a bare name (`npx`, `uvx`, `mcptoon`) or a
`./`-relative path inside a plugin. Never a shell string, never `bash -c`.
- Absolute paths in `command` are forbidden; use PATH or `./` relative.
- `args` is a list of strings. Shell metacharacters belong in args, not in
`command`.
## Plugin entries
Agent Plugins are installed under `~/.mcptoon/plugins/<plugin>/` and merged
automatically with `"<plugin>:<server>"` names. Their paths can use
placeholders, expanded at install time:
- `${PLUGIN_ROOT}` — the installed plugin directory
- `${PLUGIN_DATA}` — the plugin's persistent data directory (survives upgrades)
Plugin-managed entries should be edited by updating the plugin (reinstall with
`--force`), not by hand-editing the merged config.
## Validation loop (always run after writing)
```bash
mcptoon doctor # catches syntax, missing binaries, bad urls
mcptoon list # confirm the server is visible
mcptoon health # per-server connectivity, exit 1 if anything is dead
```
If you generated the entry from documentation, prefer `mcptoon install --npm /
--pip / --url` over hand-writing JSON — it fills the correct shape for you.
## Good tool hygiene (for server authors)
- Prefer fewer, well-described tools over many overlapping ones; agents pick
tools by description.
- When a server ships a `SKILL.md` (Agent Plugins), keep the body actionable:
concrete commands, exact flags, no marketing text.