Sergio by Serviche
Customer workspaceCampaignsWhy SergioCertificationsFAQBlogLog inRequest access
Log inBook a demoRequest access

Sergio MCP quickstart

Connect an agent and make a first read

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

Before you start

  1. The server is 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.
  2. You need a business to connect to. Each business approves its own connection, and one seat covers one business.
  3. No client business yet? Build against TidyHome, our demo business with made-up customers. Access is by invitation for now: request demo access.

Path A: OAuth, for AI clients

Use this when a person connects Claude, ChatGPT, Cursor or another MCP client to their business.

  1. In the client, add a custom connector or remote MCP server with the server address above.
  2. The client registers itself and opens Sergio's sign-in page (authorization code flow with PKCE S256).
  3. The owner or an admin signs in and approves the connection for their business.
  4. Ask the assistant to call whoami and check organization.name is the right business before anything else.
  5. Access tokens last 1 hour and refresh tokens 90 days; the client refreshes on its own. Step-by-step guides for ChatGPT and Claude are on the setup page.

Path B: an agent key, for scripts

Use this for a script, a scheduled job or your own backend.

  1. The business's owner or an admin opens the Team page in Sergio and chooses Add agent, then names it and picks its role (admin, manager or member).
  2. Sergio shows the key once. It starts with sgo_. Put it straight into a secret store. If it is lost, they add a new key and revoke the old one.
  3. Send it on every request as Authorization: Bearer sgo_.... The agent can read and change what a person with the same role can, and nothing more.

1. initialize (no key needed)

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 3
curl -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.

2. tools/list (no key needed)

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.

3. whoami (key needed)

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.

4. A first read: today's bookings

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}}}}'
  1. Swap in today's date. Dates are the business's own calendar days.
  2. A list answer carries 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.
  3. Call read with {"entity":"catalog"} to see every entity, filter and field your seat may read.

When something goes wrong

  1. 401: no or expired credential. Sign in again, or check the agent key was not revoked.
  2. 403: feature_not_enabled means the business does not have agents turned on. Ask the owner, or ask us.
  3. 406: the Accept header is missing one of the two types.
  4. 429: a limit (60 a minute and 4 at once per key; 180 and 8 per business). Wait for Retry-After.
  5. Any other refusal is HTTP 200 with isError: true; read structuredContent.error and message.

Next

  1. Browse every tool and its inputs in the tool reference, with the rules for limits, retries, events and sending.
  2. Build a morning briefing: read today's bookings, overdue tasks and conversations needing a reply, then print an ordered plan. Add tasks with create_task and a stable idempotency_key so a re-run never duplicates them.
  3. For new messages, subscribe to the events feed with events_subscribe, poll events_list, and events_ack what you handled.
sergio

Customer operations software for residential cleaning companies.

Product

Customer workspaceCampaignsWhy SergioCertificationsSergio MCPFor buildersFAQ

Works with

BookingKoalaConvertLabsLaunch27QuoGmail

Company

Log inBook a demoContactReferral partnersBlogServicheShowcasePrivacyTerms
© 2026 Serviche. Sergio is customer operations software for residential cleaning companies.
G2 Reviews on G2P Product Hunt