Skip to main content
Human Intelligence operates a spec-compliant Model Context Protocol server. It is the integration point used by customers who run their own internal agent harnesses, as well as by off-the-shelf clients like Claude and Notion Agents. This page is written for engineering, IT, and security teams evaluating or integrating the server. If you just want to connect a supported tool, start with Connectors.

Endpoint

The server is multi-tenanted: every customer and every user connects to this same endpoint. There is no per-tenant hostname, no per-user path, and no customer-specific configuration to distribute. Tenancy and identity are resolved from the access token presented on each request, not from the URL. In practice this means rolling the server out to a team is a single copy-pasteable value, and rotating or revoking a user’s access is an identity operation rather than a configuration change.

Authentication

The server implements the MCP authorization specification, layered on OAuth 2.1. A client that supports the spec can discover, identify, and authorize itself with no manual credential exchange — you do not need to request a client ID from us, and we do not need to pre-register your harness.

Client identification

The spec gives a client two ways to tell the authorization server who it is, and we support both: CIMD is the better choice where you have the option. The client ID is stable — it doesn’t churn a new registration per install, per deploy, or per token refresh — and because it is a URL, the client is attributable to a domain its operator controls, which shows up in consent and in our audit trail as something more meaningful than an opaque identifier.

Discovery

The server exposes the two discovery documents the spec requires: An unauthenticated request to the MCP endpoint returns 401 with a WWW-Authenticate header carrying the resource_metadata URL, so a compliant client can bootstrap the whole flow from the endpoint alone. Authorization server metadata advertises both mechanisms — client_id_metadata_document_supported: true and a registration_endpoint — so a client discovers which to use rather than being configured for it:

Authorization flow

A first-time connection follows the standard sequence:
1

Discover

The client fetches the protected-resource metadata, follows it to the authorization server, and reads its metadata.
2

Identify

The client presents its client ID — either its metadata-document URL (CIMD), or an opaque ID it obtains by registering dynamically at the registration endpoint.
3

Authorize

The user is redirected to the Human Intelligence sign-in page and signs in as they normally would, then grants the client access.
4

Exchange

The client exchanges the authorization code for an access token and uses it as a bearer token on subsequent requests.

Tokens

Access tokens are JWTs. The server verifies each one against the authorization server’s published JWKS and checks that it is audience-bound to this resource — a token minted for a different resource, or for a different environment, is rejected rather than honored. Tokens are presented in the Authorization header; the server does not accept credentials in query parameters. Rejections that indicate a token problem — expired, malformed, wrong signing key, wrong audience — return 401, signalling the client to re-authenticate. Server-side faults return 5xx so clients don’t discard a valid token in response to an outage.
Sign-in uses whatever authentication your organization has configured in Human Intelligence. Connecting an MCP client does not create a second set of credentials or a separate identity to manage. See Security.

Transport and scaling

The server speaks Streamable HTTP, with MCP JSON-RPC requests sent over POST. It is stateless. No session identifier is issued and no server-side session state is retained between requests, so no sticky-session or session-affinity configuration is required on your side. Each request is independently authenticated and independently routable, which is what allows the server to scale horizontally behind a single endpoint.

Versioning

The tool contract is versioned, and you can pin to a specific version:
The unversioned /mcp path serves the current default version, 0.9.0, and moves forward when a new version becomes the default. The latest version is 0.11.0. Interactive assistants such as Claude can use /mcp and pick up improvements automatically. Pin a version for anything built against specific tool calls, such as an internal app or an agent harness tuned to a tool contract, so a server-side release doesn’t change tools or response shapes underneath it. Breaking changes always ship first as a new version you can test, and the default only moves to one on a date we announce in advance. See Versions for what changed in each version, the full tool list per version, and migration notes for breaking changes.
Pin in production and test the latest version in development. That way you find out about a contract change on your own schedule rather than during an incident.

Identity and permissions

Every MCP session acts as a specific Human Intelligence user — the person who completed the authorization flow. There is no service account, no shared API key, and no ambient tenant-wide access. This has a consequence worth stating plainly to a security reviewer: connecting an AI tool does not widen anyone’s access. A user who cannot see compensation data in Human Intelligence cannot see it through an MCP client either, no matter what the client asks for. Enforcement happens server-side, not in the client or the model:
  • Row-level security restricts which rows a query can return, based on the access rules and organizational boundaries configured for that user’s roles.
  • Category permissions restrict which metrics, dimensions, and segments are visible at all. Members the user isn’t permitted to see are not returned in schema responses, so a model cannot request what it cannot be shown.
  • Governed definitions mean results reflect your organization’s own metric methodology rather than the model’s interpretation of a column name.
  • Narrative policies, where your organization has configured them, are evaluated against each query and the user’s stated intent. From version 0.11.0 this happens inside every data query, so a client cannot skip it.
Because these are applied on the server, they hold regardless of which client is connected or how it is prompted. A client can only ever be told less than the full picture — never more.
Results reflect the connected user’s access scope. When access rules have limited what a query could see, the response says so, and the tool contract instructs the client to describe the figures as scoped rather than as org-wide.

Auditing

Tool calls are audited server-side, including the acting identity. Query activity surfaced through MCP is subject to the same audit trail as activity in the product — see Audit log.

Available tools

The server exposes a small set of tools for discovering datasets, inspecting their schema and methodology, running governed analytical queries, and paging results. Some tools are registered conditionally, so the exact set a client sees depends on your organization’s configuration. See the tool reference for the full list and what each one does.

Connecting a custom client

If you’re building your own harness, point any spec-compliant MCP client library at the endpoint and let it run the OAuth flow. Because the server accepts both CIMD and dynamic registration, there is no onboarding step on our side.

Identifying a hosted harness with CIMD

For a harness you host, publish a client metadata document and use its URL as your client_id:
https://harness.example.com/oauth/client
A few requirements are worth checking before you debug an authorization failure:
  • The document must be served over HTTPS at the exact URL used as client_id, publicly fetchable with no authentication, as application/json.
  • The client_id inside the document must match the URL it is served from, compared as an exact string.
  • The URL needs an explicit path, and no fragment, embedded credentials, or dot segments.
  • client_name and redirect_uris are required. client_name is what your users see on the consent screen, so make it the name they’d recognize.
See the Client ID Metadata Document draft for the full specification. If your harness runs locally and redirects to a loopback address, there’s nothing to host — register dynamically instead and let the client library handle it. To validate a connection before wiring it into your harness, the MCP Inspector is the fastest path: point it at the endpoint, complete the sign-in, and confirm that tools/list returns the expected tools and that whoami reports the identity you expect.
whoami is the quickest way to confirm which account, roles, and permissions a session is operating under — useful when a harness returns less data than a colleague expects and you need to determine whether that’s a bug or correct enforcement.