Skip to content
Toado Docs

Contributing

The MCP server lives at github.com/toado-dev/toado-mcp under the MIT licence, published on npm as @toado/mcp. That repo is the whole server, the HTTP transport behind the hosted endpoint at mcp.toado.dev included: one repo, one package, with no hosted-only code held back. Issues and pull requests there are the public channel for anything MCP-specific. Product requests that are not about the MCP server go to Feature requests and the roadmap.

Filing an issue

Open an issue on the repo. Include:

  • The client and version (Claude Code, Cursor, Codex, Claude Desktop, or your own).
  • Whether you are on the hosted endpoint at mcp.toado.dev or running the server from source.
  • The tool name and the arguments you passed, with ids redacted if you prefer.
  • The error the tool returned. MCP errors are JSON; paste the whole object.
  • For a 401 or 429, the response headers (WWW-Authenticate, Retry-After).

Never paste a token. If you did by accident, revoke it in Company settings > MCP tokens before doing anything else.

Security issues do not go in public issues. Email security@toado.dev; see Incident reporting.

Pull requests

  1. Fork, then branch from main.
  2. pnpm install, pnpm build, pnpm test. All three must pass before you open the PR.
  3. Keep the PR to one change. A fix and an unrelated refactor are two PRs.
  4. Reference the issue it closes.
  5. Do not bump the version in package.json. Releases are cut by maintainers; see Release cadence.

Reviews usually land within a few business days. A PR that changes a tool’s inputs or outputs takes longer because it needs the matching change in the knowledge base repo.

Adding a tool

Every tool is one entry in the tools array in src/tools.ts. Four pieces, all in the same PR.

1. Schema. Add a zod object to schemas. Use snake_case argument names, .describe() on anything not obvious, and .max() on every list and page size. The schema becomes the tool’s JSON Schema, so the descriptions are the documentation an agent reads before calling it.

2. Handler. Add the ToolDef with name, description, inputSchema, requiredScope and handler. The handler parses its input with the schema, calls the API through ctx.api, and returns plain data; server.ts serialises the result and maps ApiError for you. Reads use MCP_SCOPES.READ; writes use the narrowest write scope that fits. Strip DevTools blobs from write responses with trimTicketForWriteResponse. Log to stderr only.

3. Test. Add a test under test/ that calls tool.handler with a stubbed ApiClient and asserts the API path, the query, and the returned shape. test/recording-assets.test.ts is the pattern to copy. pnpm test must stay green.

4. Regenerate the tools JSON. Use the public repository’s pnpm gen:tools-json to inspect that checkout’s tool schema. Coordinate the knowledgebase update with the matching application source revision using its reference-generation workflow, so newer tools and canonical scopes are preserved. Review the generated diff and any related prose on the Tools reference.

What will not be accepted

  • Anything that changes the API contract without a backend change. The server is a thin proxy over the REST API. A tool that invents a field the API does not return, papers over an API error, or calls an endpoint that does not exist yet is a backend change in disguise. File an issue describing the need instead.
  • Tools that bypass scopes. Every tool declares one required scope and the check runs before the handler. A PR that relaxes this, or reads through a write path to skip a check, is closed.
  • New rate-limit or auth exemptions. The per-IP limit and the bearer requirement on /mcp are not configurable per deployment.
  • Writing to stdout. All logging goes to stderr. A PR that adds a console.log gets a review comment, not a merge.
  • Renaming existing tools. Renames break every installed skill. A rename is a deprecation with a new tool alongside, agreed in an issue first.

Code of conduct

Participation in the repo is covered by its code of conduct: CODE_OF_CONDUCT.md. Report conduct issues to hello@toado.dev.

Where to next