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 with Dynamic Client Registration (RFC 7591). A client that supports the spec can discover, register, 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.

​
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 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

Register

The client registers itself dynamically and receives a client ID.
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 current published version is 0.5.0. Requesting the unversioned /mcp path routes to the current default version, which advances over time as new versions ship. For interactive clients like Claude or Notion Agents, use the unversioned endpoint — you’ll pick up improvements automatically. For an internal agent harness where prompt behavior is tuned against a specific tool contract, pin the version so a server-side release doesn’t change tool descriptions or response shapes underneath your harness.
Pin in production, track the default 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 the user’s intent before data tools run.
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 registration is dynamic, there is no onboarding step on our side. 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.