# 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.

- Source: https://greenhired.com/developers/mcp/protocol/
- Section: GreenHired developers · MCP server · Reference
- Last updated: 2026-11-21

## 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 https://mcp.greenhired.com/mcp`**: One JSON-RPC message in, one JSON answer out.

**List the tools**

```bash
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 wrong | How 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 JSON | JSON-RPC `-32700` |
| Not a valid request (also a batch) | JSON-RPC `-32600` |
| Unknown method | JSON-RPC `-32601` |
| Bad params (unknown tool, arguments that are not an object, `get_job` without a `slug`) | JSON-RPC `-32602` |
| A failure inside the API | JSON-RPC `-32603` |
| The API cannot be reached | A plain `503` |

> **Note:** A client library may raise an exception for a refused credential instead of showing the model the message. That is the standard way for a server to refuse credentials.

## 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.

## Related pages

- https://greenhired.com/developers/mcp/tools/
- https://greenhired.com/developers/mcp/authentication/
- https://greenhired.com/developers/api/v1/limits/
