Sergio MCP quickstart
About ten minutes: connect to a cleaning business's Sergio account, confirm which business you are in, and read today's bookings.
Tool reference · Why build on Sergio · ChatGPT and Claude setup
https://sergio.serviche.com/api/agent/mcp: MCP over Streamable HTTP, stateless, POST only, JSON answers. Every request stands on its own and carries its own credential.Use this when a person connects Claude, ChatGPT, Cursor or another MCP client to their business.
whoami and check organization.name is the right business before anything else.Use this for a script, a scheduled job or your own backend.
sgo_. Put it straight into a secret store. If it is lost, they add a new key and revoke the old one.Authorization: Bearer sgo_.... The agent can read and change what a person with the same role can, and nothing more.Every request needs Content-Type: application/json and Accept: application/json, text/event-stream. Without both types in Accept the server answers 406.
export SERGIO_MCP_URL=https://sergio.serviche.com/api/agent/mcp
export SERGIO_AGENT_KEY=sgo_your_key_here # only needed from step 3curl -s -X POST "$SERGIO_MCP_URL" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-script","version":"0.1.0"}}}'You get the server's name (sergio), its capabilities and short instructions for agents.
curl -s -X POST "$SERGIO_MCP_URL" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'Without a key you get the public catalog, the same list as the tool reference. With a key you get the tools your seat can use in that business.
curl -s -X POST "$SERGIO_MCP_URL" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $SERGIO_AGENT_KEY" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'The result's structuredContent names the seat (name, role), the business (organization.id, organization.name) and the key used. Check the business name before you go further.
Without the Authorization header this call returns HTTP 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource.
curl -s -X POST "$SERGIO_MCP_URL" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $SERGIO_AGENT_KEY" \
-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"read","arguments":{"entity":"bookings","filters":{"from":"2026-11-13","to":"2026-11-13"},"options":{"limit":100,"offset":0}}}}'returned, total and truncated. When truncated is true, read again with options.offset set to next_offset (or offset + returned when there is none). options.limit goes up to 100.read with {"entity":"catalog"} to see every entity, filter and field your seat may read.feature_not_enabled means the business does not have agents turned on. Ask the owner, or ask us.Accept header is missing one of the two types.Retry-After.isError: true; read structuredContent.error and message.create_task and a stable idempotency_key so a re-run never duplicates them.events_subscribe, poll events_list, and events_ack what you handled.