Authentication

Connecting to the server and browsing the catalog (search_datasets, list_facets, get_dataset, get_chart_colors) never requires auth — see Public vs. gated. The tools that return actual dataset rows (query_dataset_rows, aggregate_dataset, distinct_dataset_values) do, unless the dataset is currently keyless.

When auth is needed, the server accepts two kinds of bearer token, tried in order. Pick whichever fits your client — tools behave identically either way.

OAuth (interactive clients)

Add just the endpoint URL, with no header:

{
  "aesops": {
    "url": "https://aesops.co.ke/api/mcp"
  }
}

A client that supports MCP's OAuth discovery flow (Claude Desktop, Claude Code) detects the requirement from /.well-known/oauth-protected-resource, opens your browser to Aesops' sign-in page, and stores the resulting token itself — no key to copy anywhere. Sign in the same way you would on aesops.co.ke (email code, GitHub, or Google).

API key (scripted / CI / headless clients)

Create a read-scoped API key at aesops.co.ke/profile/api-keys — the same key type used by the REST API and the Python SDK. Send it as a static header:

{
  "aesops": {
    "url": "https://aesops.co.ke/api/mcp",
    "headers": {
      "Authorization": "Bearer <your-key>"
    }
  }
}

Which one wins

The server checks for a valid OAuth session first; if that's absent (no token, or one that doesn't resolve to a session), it falls back to validating the bearer token as an API key. Whichever path succeeds resolves to an equivalent read-scoped identity — no tool cares which one authenticated the request.

What happens without a token

Calling a query tool with no token (or an invalid one) against a non-keyless dataset doesn't fail the connection — the server itself never returns 401 for a missing token, since browsing is meant to work unauthenticated. Instead the tool call succeeds at the transport level and returns a plain error result:

{ "error": "This dataset requires authentication to query — connect via OAuth or an API key. See https://docs.aesops.co.ke/docs/mcp/authentication." }

Connect a client with a token to resolve it, or check whether the dataset is currently keyless — see Keyless datasets.