Documentation · 9 October 2026

Developer quickstart

Send one JSON-RPC 2.0 message per HTTP POST to https://www.digitaljobs.com/mcp. Public examples below require no token. The endpoint returns JSON, does not issue a session ID and does not offer a GET event stream.

MCP 2025-11-25

This sequence matches the legacy path tested against the live service. Run the commands in a shell with curl installed.

Initialise

curl --silent --show-error --max-time 30 'https://www.digitaljobs.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"digitaljobs-example","version":"1.0"},"capabilities":{}}}'

Expect HTTP 200 and result.protocolVersion equal to 2025-11-25. The current implementation only accepts that exact version in initialize. Do not send 2026-07-28 through this initialization path.

Notify readiness

curl --silent --show-error --max-time 30 'https://www.digitaljobs.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'

Expect HTTP 202 with an empty body. No request ID is included in the notification.

List available tools

curl --silent --show-error --max-time 30 'https://www.digitaljobs.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

The tool catalogue is returned in one page. Do not supply a catalogue cursor. The server advertises enabled tools regardless of your scopes; enforce authorisation by handling each call's response.

Search

curl --silent --show-error --max-time 30 'https://www.digitaljobs.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_jobs","arguments":{"role":"developer","limit":2}}}'

Read result.structuredContent.jobs. The text in result.content is a summary, not a JSON copy of the records. Check for a top-level error and result.isError before consuming data. Fetch another page with only {"cursor":"RETURNED_CURSOR"} in arguments.

MCP 2026-07-28

Use server/discover instead of legacy initialization. Every modern request requires the version header, matching Mcp-Method and the three metadata fields shown below. Tool calls also require Mcp-Name matching params.name. Metadata belongs under params._meta, outside arguments.

curl --silent --show-error --max-time 30 'https://www.digitaljobs.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"digitaljobs-example","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

Then request tools/list with Mcp-Method: tools/list and the same metadata. To search:

curl --silent --show-error --max-time 30 'https://www.digitaljobs.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search_jobs' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_jobs","arguments":{"role":"developer","limit":2},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"digitaljobs-example","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

Modern successful results include resultType: "complete". Discovery and the catalogue include a five-minute TTL. Do not confuse catalogue freshness with the availability or current state of individual job records.

Protected calls

Complete OAuth and linking, then use the same tools/call envelope with an Authorization: Bearer <access_token> header and the tool's input object. Have the client manage credentials securely; do not paste them into chat or commit them to source control. Omit the header entirely for anonymous requests; an invalid token is rejected even for a public tool.

Use JSON integers for creation IDs and strings for draft_id. Request bodies are limited to 64 KiB. Unknown arguments and invalid types are rejected. Batch request arrays, resources and prompts are not supported by this implementation.

Response handling

Record the HTTP status and X-Request-Id when available.
Handle a top-level JSON-RPC error as a request failure.
Check result.isError; a business-rule failure can arrive with HTTP 200.
On success, read structuredContent and preserve returned URLs and IDs.
Honour Retry-After and use bounded retries. Reuse the same idempotency key for an uncertain draft-creation outcome.

Browser-to-server integrations need deliberate origin and CORS support. The current PHP router validates origins but does not emit CORS allow headers. Use a supported server-side or native client; do not disable browser protections.

The current empty-object schema issue may stop strict MCP libraries before any call is made. This quickstart demonstrates HTTP behaviour; it does not establish compatibility with every MCP SDK. See troubleshooting.

Transport reference: MCP Streamable HTTP. Newer protocol reference: MCP 2026-07-28.