Developer documentation

MCP server

The Model Context Protocol endpoint is https://saleshog.co/mcp (JSON-RPC 2.0 over HTTP). Authenticate with Authorization: Bearer <access_token>. Initialize first, list tools, then call them.

{
  "mcpServers": {
    "saleshog": {
      "url": "https://saleshog.co/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

Tools include getBusinessInfo, getSignals, getMentions, getMetrics, getWeeklyReport, getTrendingIssues, draftOutreach, showDraft, sendOutreach, getUsage, and more. Run tools/listfor each tool’s typed input schema. Outreach always requires explicit user approval in the product before anything is sent.

Machine-readable resources

• OpenAPI spec: https://saleshog.co/openapi.json — full API surface with typed schemas and unique operation IDs.
• Agent instructions (llms.txt): https://saleshog.co/llms.txt
• Authorization server metadata: https://saleshog.co/.well-known/oauth-authorization-server (RFC 8414)
• Protected resource metadata: https://saleshog.co/.well-known/oauth-protected-resource

Authentication (OAuth 2.1)

MCP clients authenticate with OAuth 2.1 + PKCE (S256) and dynamic client registration. Only public clients are supported, and redirect URIs must be HTTPS or loopback (127.0.0.1 / localhost). The supported scope is mcp. Most MCP clients (Claude, Cursor, and similar) handle registration and the token dance automatically — you only paste the server URL.

curl -X POST https://saleshog.co/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["https://your-app.example/callback"],
    "client_name": "Your App",
    "token_endpoint_auth_method": "none"
  }'

Send the user to https://saleshog.co/oauth/authorize with response_type=code, your client_id, redirect_uri, scope=mcp, and a PKCE code_challenge. The user sees exactly what the agent can access and approves the connection themselves.

curl -X POST https://saleshog.co/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "code_verifier=PKCE_VERIFIER" \
  -d "redirect_uri=https://your-app.example/callback" \
  -d "client_id=YOUR_CLIENT_ID"

Access tokens last one hour; refresh tokens last 30 days. Revoke tokens at https://saleshog.co/oauth/revoke.

MCP server

The Model Context Protocol endpoint is https://saleshog.co/mcp (JSON-RPC 2.0 over HTTP). Authenticate with Authorization: Bearer <access_token>. Initialize first, list tools, then call them.

{
  "mcpServers": {
    "saleshog": {
      "url": "https://saleshog.co/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

Tools include getBusinessInfo, getSignals, getMentions, getMetrics, getWeeklyReport, getTrendingIssues, draftOutreach, showDraft, sendOutreach, getUsage, and more. Run tools/listfor each tool’s typed input schema. Outreach always requires explicit user approval in the product before anything is sent.

Errors

All API error responses are structured JSON with a machine-readable code and a resolution hint. Agents should read code rather than parsing text.

HTTP/1.1 401 Unauthorized
{
  "error": "Authentication required",
  "code": "unauthorized",
  "message": "Authentication required",
  "hint": "Sign in to obtain a session cookie. For machine access see /docs and /openapi.json."
}

Codes: bad_request, unauthorized, forbidden, not_found, method_not_allowed, conflict, rate_limited, server_error. Unknown API paths return the same JSON shape with HTTP 404.