Connect and Authenticate

Get access, authenticate, and make your first call to the Thumbtack MCP Server.

Server Details

Property	Value
Server Name	Thumbtack MCP Server
Version	1.0.0
Transport	Streamable HTTP (JSON-RPC 2.0)
Response Format	Standard JSON (Content-Type: application/json), no Server-Sent Events
Session Management	Stateless (no Mcp-Session-Id validation)
Production MCP Endpoint	https://mcp.thumbtack.com/mcp
Staging MCP Endpoint	https://staging-mcp.thumbtack.com/mcp
SDK	Built with the official MCP Go SDK

Endpoints

Path	Methods	Description
/mcp	POST	Main MCP JSON-RPC endpoint. In stateless mode there is no SSE stream, so GET returns 405 Method Not Allowed.
/.well-known/oauth-protected-resource	GET, OPTIONS	OAuth 2.0 Protected Resource Metadata: the resource URL, the authorization server, and the supported scopes
/.well-known/oauth-protected-resource/mcp	GET, OPTIONS	Same metadata, at the MCP-specific path

Stateless Design

The server operates in stateless mode, meaning it does not track sessions across requests. This design ensures reliable behavior when requests are load-balanced across multiple server instances. Clients do not need to manage or send Mcp-Session-Id headers.

Getting Access

Thumbtack provisions access during partner onboarding. You receive:

An OAuth client ID and client secret, separately for staging and production.
The toolset enabled for your client. For the Preset Job Toolset, Thumbtack also configures the categories you can book.

Authentication

Every request to /mcp must carry a Thumbtack OAuth access token, including discovery calls such as initialize and tools/list. The server uses the token to identify the partner and return that partner's toolset. For how Thumbtack OAuth works, including the client credentials flow and scopes, see Authentication.

1. Get an access token

Use the OAuth 2.0 client credentials grant against Thumbtack's authorization server:

curl -X POST https://auth.thumbtack.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d audience=urn:partner-api \
  --data-urlencode "scope=demand::businesses/search.read demand::categories.read demand::categories/request-form.read demand::businesses/reviews.read"

On staging, use https://staging-auth.thumbtack.com/oauth2/token. The response contains access_token and expires_in. Cache the token and request a new one before it expires.

2. Send the token on every request

Authorization: Bearer <access_token>

Scopes

Scope	Needed for
demand::businesses/search.read	Required on every tool call
demand::categories.read	Required on every tool call
demand::categories/request-form.read	Required on every tool call
demand::businesses/reviews.read	Required on every tool call
demand::orders/availability.read	Preset Job Toolset only
demand::order-configurations/request-form.read	Preset Job Toolset only
demand::order-configurations/times.read	Preset Job Toolset only
demand::orders/price.read	Preset Job Toolset only
demand::orders.write	Preset Job Toolset only
demand::orders/preset-job.write	Preset Job Toolset only
demand::orders.read	Preset Job Toolset only

A tool call whose token lacks any of the four required scopes is rejected with 403 Forbidden. Preset Job partners should request all eleven scopes.

IP allowlisting

For a small number of platform partners, Thumbtack instead identifies requests by their egress IP addresses and obtains tokens on the partner's behalf. This is set up case by case. New integrations should use OAuth.

Connecting to the Server

Point your MCP client at the endpoint for your environment:

https://mcp.thumbtack.com/mcp            (production)
https://staging-mcp.thumbtack.com/mcp    (staging)

Send these headers on every POST:

Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

The Accept header must list both types, even though the server always responds with application/json. Then call initialize and tools/list to enumerate your toolset and its schemas.

/.well-known/oauth-protected-resource publishes the authorization server (https://auth.thumbtack.com) and the supported scopes. It does not replace onboarding: you need a client ID and secret from Thumbtack to get a token.

Example Tool Call

curl -X POST https://mcp.thumbtack.com/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_home_service_pros",
      "arguments": {
        "userQuery": "I need a plumber to fix a leaky faucet",
        "zipCode": "94102"
      }
    }
  }'

Example Response

Tool results are returned in the result field. structuredContent holds the structured output, and content holds the same JSON as text for clients that don't read structuredContent. The example below is abridged:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "{\"searchID\":\"560060166177587213\", ...}"}],
    "structuredContent": {
      "searchID": "560060166177587213",
      "categoryID": "122325513795633420",
      "categoryName": "Plumber",
      "data": [
        {
          "businessID": "392575385842925569",
          "businessName": "SF Plumbing Pros",
          "rating": 4.8,
          "numberOfReviews": 142,
          "priceInfo": "$95/hr",
          "servicePageURL": "https://www.thumbtack.com/ca/san-francisco/plumbers/..."
        }
      ],
      "metadata": {
        "categoryID": "122325513795633420",
        "categoryName": "Plumber",
        "zipCode": "94102",
        "requestLocation": "San Francisco, CA"
      },
      "requestForm": {
        "requestFormID": "544309887982174213",
        "questions": [
          {
            "questionID": "100001",
            "prompt": "What kind of plumbing issue do you have?",
            "questionType": "radioOption",
            "isClarifyingQuestion": true,
            "answerOptions": [
              {"text": "Leaky faucet", "answerID": "200001"},
              {"text": "Clogged drain", "answerID": "200002"},
              {"text": "Pipe repair", "answerID": "200003"}
            ]
          }
        ]
      },
      "relevantCategories": [
        {"categoryID": "987654321", "name": "Water Heater Installation"}
      ]
    }
  }
}

Last Updated: Oct 21st, 2026

On this page