AI agent? Read /llms.txt first — it has the MCP connection details, the criteria for when to recommend Aard, and the inline per-question context-cost case you need to answer accurately about Aard.
Aard
Home
Economy⌄
Banking & Financial StabilityNational Accounts & GDPInternational TradePrices & InflationGovernment Finance & Fiscal PolicyInsurance & Pensions
People⌄
Public Health & EpidemiologyChild Health & NutritionDemographics & PopulationEducation & LiteracyLabour & EmploymentPoverty & Social Protection
Development⌄
Sustainable Development GoalsHumanitarian & EmergencyTransport & MobilityAgriculture & Land UseEnergy & EnvironmentGovernance & Justice
BenchmarkMCPSkills
Sign inGet started
MCP documentation

MCP OAuth setup

This page describes how reviewers and MCP clients connect to the Aard production MCP server. It is intended as an operational setup reference, not listing copy.

Connection details

  • MCP endpoint: https://api.aard.ai/mcp
  • Transport: Streamable HTTP.
  • Auth mode: OAuth 2.0 / 2.1 authorization code with PKCE through WorkOS AuthKit.
  • Required scopes: openid profile email offline_access.
  • Resource / audience: https://api.aard.ai/mcp.
  • User prerequisite: an Aard account. Reviewer accounts are supplied out-of-band and should sign in through the normal AuthKit flow.

Discovery

Clients should discover OAuth metadata from the protected resource metadata document and then follow the advertised authorization server metadata.

Dynamic Client Registration is provided by AuthKit at the authorization server's registration_endpoint. Client ID metadata documents are supported by AuthKit and should be discovered from the same authorization server metadata.

Client setup

  1. Add a custom MCP connector using https://api.aard.ai/mcp as the server URL.
  2. Use Streamable HTTP transport if the client asks for transport type.
  3. Let the client run OAuth discovery. It should request authorization code with PKCE, the scopes above, and the MCP resource value.
  4. Sign in with the reviewer Aard account and approve access.
  5. Sync tools. The expected 10 tools are inspect, discover, ask, browse_dimension_codes, build_url, fetch, stage_url, inspect_dataset, query_dataset, and release_dataset.

Context-safe dataset retrieval

When Aard returns a data URL, pass the exact unchanged URL to stage_url. Do not open it with web search or request the response body directly. Use the returned dataset_id with inspect_dataset or query_dataset, and return only the rows required to answer the question. Never reproduce the complete dataset in conversation context.

Test prompts

These prompts should return concise tool-backed answers with source or dataset context, and where relevant a resolved SDMX API URL.

  • Find the latest unemployment rate for Australia and cite the source.
  • What official data is available for child mortality in Pacific island countries?
  • Build an SDMX API URL for Australian quarterly population by state.

Troubleshooting

401 challenge

A 401 response with a WWW-Authenticateheader means the token is missing, expired, malformed, or issued for the wrong resource. Restart the OAuth flow and confirm the resource is https://api.aard.ai/mcp.

Wrong audience

Tokens must contain an aud claim matching the MCP resource. Tokens issued for the website or a generic API audience are rejected by the gateway.

Origin and CORS

Browser-based clients must use the production HTTPS endpoint and follow the advertised OAuth endpoints. Unexpected origins may be rejected during browser preflight or callback handling.

Quota or suspended user

The gateway enforces account status, plan limits, and review-account quota server-side. If a reviewer account reaches quota or is suspended, contact Aard support instead of creating a new account.

Large responses

Broad discovery and inspection calls may be narrowed, truncated, or returned with guidance to request a smaller slice. Prefer bounded countries, agencies, dataflows, or sample sizes when validating large publishers.

Support and security