MCP server · Reference

MCP protocol notes

How the GreenHired MCP server behaves on the wire: stateless Streamable HTTP, one request one count, JSON-RPC errors, refused batches, size and time limits.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Transport
  2. One MCP request is one request on the key
  3. Errors
  4. Choices that may surprise you
  5. Frequently asked questions

#Transport

The server implements MCP protocol version 2025-03-26 over Streamable HTTP in its simplest, stateless form. Send one JSON-RPC 2.0 message per POST to https://mcp.greenhired.com/mcp with Content-Type: application/json, and read one JSON answer. GET /mcp is 405 because there is no stream to open. Health check: https://mcp.greenhired.com/health.

POST/mcpmcp.greenhired.comany valid key

One JSON-RPC message in, one JSON answer out.

List the tools
curl
curl -s https://mcp.greenhired.com/mcp \
  -H "Authorization: Bearer $GREENHIRED_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

#One MCP request is one request on the key

Whatever the message is, it counts as exactly one request against your limits. A tool call is the one call to the API behind it. Everything else (initialize, ping, tools/list, a notification, a malformed message) is answered after one GET /v1/ping, which proves the key is valid. Nothing in a body is read before the key has passed.

For a sign-in connection, every request is one counted call on the person's connection: a tool call is the tool's own call, anything else is answered after one GET /v1/assistant/me on the account API. That connection has 120 requests and 30 changes a minute.

#Errors

What went wrongHow it is reported
The request is wrong for the API (a bad filter, a bad cursor, an unknown argument, a job that does not exist or has closed)A normal result with isError: true and the API's { "error": { "code", "message" } } as text
The key or token (401 missing, invalid or revoked; 403 missing permission; 429 limit; 503 switched off)The plain HTTP answer, with X-RateLimit-* and Retry-After where they apply
The message is not JSONJSON-RPC -32700
Not a valid request (also a batch)JSON-RPC -32600
Unknown methodJSON-RPC -32601
Bad params (unknown tool, arguments that are not an object, get_job without a slug)JSON-RPC -32602
A failure inside the APIJSON-RPC -32603
The API cannot be reachedA plain 503

#Choices that may surprise you

  • Batches are refused (-32600): one message per request. A batch of N tool calls would be N requests on the key, and the rule above is what makes the limits mean something.
  • Size and time: a request body is read by bytes and cut at 64 KiB. The call to the API follows no redirect and times out after 15 seconds.
  • Only your credential goes to the API: Authorization and X-API-Key as you sent them. No cookie, no other header, no body.
  • A slug argument must be a plain slug (letters, digits, -, _, up to 200 characters), or the call is -32602. null arguments count as not given.

#Frequently asked questions

Why are batches refused?
The 2025-03-26 text says servers must accept batches, but a batch of N tool calls would be N requests on one key. Refusing them keeps "one MCP request is one request" true. Real clients rarely send a batch, and later protocol revisions dropped batching.
Does initialize count against my limit?
Yes, as one request, like everything else the server answers.
Why no server-sent events?
The server holds no state and has nothing to stream. Every call is a single request and a single answer.