Minerva MCP

The hosted Minerva MCP server lets a coding agent such as Codex, Claude Code, Kimi, or opencode call Minerva directly. There is no local process to run: you register one URL in the agent’s configuration, run that agent’s login command, and approve the request in the browser. The agent stores its own token, so no credential is hand-pasted in the normal flow. Use the MCP server when you want an agent to work with Minerva data itself: run screening searches, read profiles and potential matches, work with risk assessment tasks, and start or resend identity verification sessions. The scopes you grant decide which of those the agent can reach. An MCP token is a per-user credential, not an application key. The organization, the token’s workspace reach, and its permissions all come from the token itself, so an agent can only ever do what the person who authorized it may do. Minerva never accepts an application API key on the MCP endpoints. Connecting an agent? Start at Connect your coding agent, or go straight to Personal access tokens if your automation has no browser; Troubleshooting covers failed logins and missing tools. Administering an organization? Start at Admin enablement and Scopes.

Hosted MCP access is off by default. Someone with the Admin role or above has to enable it for your organization, and choose which permissions agent tokens may carry, before anyone can connect. See Admin enablement.

Before you begin

Confirm someone with the Admin role or above has enabled the hosted MCP token policy and allowed the scopes your agents need.
Confirm your own team role meets the Minimum team role set in that policy.
Install a coding agent that supports remote MCP servers over HTTP.
Decide the token’s reach: one workspace, or every workspace in the organization.
For headless use, prepare a secrets manager to hold a personal access token.

A pinned token can only ever act in the workspace it names.

Key concepts

Concept	What it means
MCP	Model Context Protocol. The convention coding agents use to discover and call external tools. Minerva hosts a server, so no local process is required.
Resource URL	The MCP endpoint an agent connects to. This is the value you register in the agent’s configuration.
Authorization server	The OAuth 2.1 endpoints that issue agent tokens. Minerva serves these on the same hostname as the MCP endpoint, so there is only ever one host to allowlist.
Scope	One named permission on a token, such as `screening:search`. A token carries an explicit list of them.
Downscoping	Minerva grants the overlap of what the agent asked for, what the tenant policy allows, and what your role and products permit. Asking for more grants less.
Hosted MCP access policy	The per-organization setting deciding whether MCP tokens may be created at all, the minimum team role, and the full set of scopes any token may ever carry.
Personal access token (PAT)	A bearer token for automations that cannot open a browser. Draws on the same scope catalog, minus the two scopes only browser consent can grant.
Entitlement	Product access granted to an organization, sometimes per workspace rather than across all of it: ID verification is organization-wide, the agent risk assessment beta is per workspace. An entitlement is not a permission, but some scopes require one.

The Minerva MCP server

Minerva publishes two resource URLs on the same hostname:

Endpoint	Use it for
`https://mcp.gominerva.com/mcp`	The full server. Whatever the token’s scopes permit, including writes.
`https://mcp.gominerva.com/mcp/readonly`	The read-only tool subset. Mutating tools are not advertised at all, whatever the token carries.

Prefer the read-only endpoint whenever an agent only needs to look things up. It removes the possibility of an accidental write even if a token is broader than it should be, so it is the right default for an autonomous agent. You can register both. Most clients allow more than one MCP server, so a common setup is a minerva entry pointing at the full endpoint for day-to-day work, paired with a minerva-readonly entry for agents you want structurally unable to change anything. Minerva serves the OAuth 2.1 authorization server on the same hostname, mcp.gominerva.com, so the discovery documents, the authorize and token endpoints, and the signing keys all live alongside the MCP endpoint. If your network policy requires an allowlist, one hostname is enough. These endpoints are separate from the REST API in the API introduction: an MCP token’s scopes apply to MCP only, and never change what an application API key can do.

Compliant clients discover all of this automatically from https://mcp.gominerva.com/.well-known/oauth-protected-resource and https://mcp.gominerva.com/.well-known/oauth-authorization-server. You should never need to configure an authorization URL, a client ID, or a client secret by hand: Minerva supports dynamic client registration, so the agent registers itself on first login.

Connect your coding agent

Setup is the same everywhere: register the resource URL, then run the client’s login command and approve the request in the browser. Each harness has its own tab below.

Step 1: Register the server

Codex, Claude Code, and opencode each write their own manifest entry from the command line. Kimi has no MCP subcommand, so you add its entry to ~/.kimi-code/mcp.json by hand.

codex mcp add minerva --url https://mcp.gominerva.com/mcp

claude mcp add --transport http minerva https://mcp.gominerva.com/mcp

opencode mcp add minerva --url https://mcp.gominerva.com/mcp

{
  "mcpServers": {
    "minerva": {
      "url": "https://mcp.gominerva.com/mcp"
    }
  }
}

codex mcp add just writes ~/.codex/config.toml. If you manage your configuration in dotfiles, add the equivalent block directly instead:

[mcp_servers.minerva]
url = "https://mcp.gominerva.com/mcp"

For a read-only agent, run the same command under a different name, with https://mcp.gominerva.com/mcp/readonly as the URL. That endpoint advertises the read-only tool subset only, so an agent wired to it cannot change anything.

codex mcp login minerva

claude mcp login minerva

opencode mcp auth minerva

Kimi has no login subcommand. It starts the browser authorization flow the first time the agent connects to the server, so just use Minerva in a session. Each command opens your browser. If you are already signed in to app.gominerva.com, you only have to approve the request.

Codex: hosted MCP login needs codex-cli 0.147.0-alpha.2 or later. As of July 2026, that version is published on npm’s alpha channel only; no stable release carries it yet. On a stable client (0.146.0 or earlier; check with codex --version) the browser approval completes and the login still fails in the terminal with Authorization server response missing required issuer, because the client enforces the issuer requirement without reading the issuer from its own callback. That is a client bug, not a Minerva one. Until 0.147.0 is stable, use a personal access token with Codex instead.

Step 3: Approve the request

The consent screen names the client that asked, the workspace the token will act in, and every scope requested. mcp:read is preselected and cannot be deselected, because a token without it cannot discover the tools it may call. Deselect anything the agent does not need. Scopes explains what each one grants. This is the last point at which you choose, and the choice is per connection, so a research agent and a case-management agent can hold very different permissions under the same account. The figure’s example policy offers optional scopes. Your organization’s policy decides which optional scopes appear. When none are available, mcp:read is the only scope on offer, and a connection carrying only that can call whoami and list_tool_permissions and nothing else. That is a working connection, not a failed one. After you approve, Minerva confirms the grant and sends the authorization to your client immediately, then tells you to finish the login in your terminal. A CLI login has just opened its listener and is blocking on it, so the authorization arrives while the client is waiting, and the tab hands you back to the client’s own confirmation. The figure below is a Codex login. The button on that screen is a fallback, not a step. If your client is still waiting, use it to send the authorization again; if your terminal has already printed success, the login is done and the page is left over. A client whose return address cannot be verified gets an error screen instead: Authorization not sent. The client is given no access, so run the login command again.

Personal access tokens

Two kinds of caller need a token rather than a browser sign-in: anything with no browser to open, such as CI jobs, schedulers, and containers, and a developer whose client cannot complete the browser login, which as of July 2026 means Codex on a stable release (see the browser flow’s Step 2: Sign in). In both cases, create a personal access token and send it as a bearer token. It draws on the same scope catalog as a browser sign-in, with one difference that matters: a personal access token cannot carry mcp:write or offline_access, which only browser consent can grant (see Scopes). Go to Administration > Developers and open Personal access tokens. The same section is on your account page. Application keys sit on that page too; see API keys for those. Creating a token asks for:

A name, so the token is identifiable later in the table
An expiry in days, up to a maximum of 90
Where this token can act: one workspace, or every workspace in the organization
The scopes it carries, offered as the intersection of the tenant policy, your team role, and your organization’s entitlements

Check the scopes on offer against the work you actually want the agent to do. A token holding only mcp:read, which is all a default organization policy allows, connects and authenticates normally but can call just two introspection tools, whoami and list_tool_permissions. Running searches needs screening:search, and reading profiles needs screening:read. The organization in this example has already allowed the screening scopes. In one that has not, this list shows Connect and list available tools on its own. The plaintext token is shown exactly once. Copy it into your secrets manager before closing the dialog; Minerva stores only a hash and cannot show it again. Send it as a bearer token on the MCP endpoint. Every client sends the same header, whatever its own configuration looks like:

Authorization: Bearer <the token you copied>

Most clients set that header for you from their configuration rather than making you write it out. The three steps below point Codex at an environment variable holding the token you just copied, so the token itself never reaches the configuration file.

Step 1: Set the environment variable

Both ways of registering the server below only name the variable, so set it first:

export MINERVA_MCP_TOKEN="<the token you copied>"

Step 2: Register the server with a bearer token

Either use the CLI:

codex mcp add minerva \
  --url https://mcp.gominerva.com/mcp \
  --bearer-token-env-var MINERVA_MCP_TOKEN

That is the browser flow’s Step 1: Register the server command with one flag added. Or, if you keep your configuration in dotfiles, write the equivalent block into ~/.codex/config.toml by hand:

[mcp_servers.minerva]
url = "https://mcp.gominerva.com/mcp"
bearer_token_env_var = "MINERVA_MCP_TOKEN"

Neither block holds the token. Both name MINERVA_MCP_TOKEN and nothing else, so the export above is the part that has to be in place whichever block you use.

Step 3: Verify the connection

codex mcp list then reports the server as enabled with Bearer token as its auth. That describes the configuration and not the credential: it reads the same whether or not MINERVA_MCP_TOKEN is set.

If the variable is not set in the environment the agent itself runs in, the connection is empty and every Minerva tool is missing, with no error. Check it there rather than in the shell you registered from.Do not run codex mcp login on top of this. The token is already the credential, so no browser flow is involved and the client-version problem above does not apply.

codex mcp add writes bearer_token_env_var, which names the variable rather than storing the token. Codex also accepts a literal Authorization value under http_headers, which puts the token in ~/.codex/config.toml, so prefer the environment variable. Set it from your secrets manager where you can: typing the export by hand puts the live token in your shell history. Codex refuses the bearer_token key outright. Setting that key fails with the message bearer_token is not supported for streamable_http. Whatever client you use, keep any file that holds a token out of source control.

The token table then tracks each token’s prefix, scopes, workspace reach, creation and last-used timestamps, and lets you revoke one without touching the others.

No Minerva MCP token lasts longer than 90 days, so every automation needs a rotation plan before it goes live. A token also acts as you for as long as it is valid. Scope it as narrowly as the automation needs, bind it to a single workspace where possible, and revoke it the moment the automation is retired or its owner changes role.

A token that reaches the end of its expiry shows as Expired, not Revoked. Nobody has to have withdrawn your access for this to happen, so read the status before assuming someone did.

When to prefer a token over the browser flow

Prefer a personal access token	Prefer the browser login
CI jobs, schedulers, and containers with no interactive browser	A developer working at a terminal on their own machine
A developer on a client whose browser login is broken, such as Codex on a stable release	A developer whose client can complete the browser login
A client that does not implement OAuth dynamic client registration	Any client that supports remote MCP servers properly
An unattended automation with a fixed, audited scope set and a rotation schedule	Short-lived, exploratory, or ad-hoc agent sessions
An environment where you must control credential rotation yourself	Cases where automatic token refresh is preferable to managing a secret

Admin enablement

Hosted MCP access is off by default. Before anyone in an organization can connect an agent, someone with the Admin role or above has to turn it on and choose what agent tokens may do. This gate is the most common reason a connection attempt fails. Go to Administration > Configuration > Authentication and open Hosted MCP access. The same page holds the SAML SSO and SCIM settings. Three settings matter:

Allow users to create hosted MCP personal access tokens is the master switch for the organization; the other two settings only matter once it is on.
Minimum team role is the lowest team role permitted to hold an MCP token. Defaults to Developer.
What tokens may do is the complete set of scopes any token in this organization may ever carry, grouped by product area, and explained in Scopes. A new policy allows only mcp:read.

This list is a ceiling, not a grant. When someone creates a token they choose from this list, narrowed again by their own team role and by the products your organization has. Allowing a scope here never gives it to anyone who could not otherwise hold it.

Leaving Minimum team role at Member while allowing administration scopes does not widen access, because each scope also carries its own role floor. The panel names any allowed scopes that sit above the policy minimum. That is informational, not an error.

Start by allowing only the connection and screening read scopes, confirm one agent connects, then add scopes as real workflows need them. Because Minerva downscopes rather than failing, a narrow policy produces a working agent with fewer tools instead of a login error.

Scopes

A token carries an explicit list of scopes. Most need a team role, and some also need an organization entitlement. The workspace-scoped ones have one wrinkle, described under the table.

Scope	Requires, and what it allows
`mcp:read`	Member. Confirm which account and workspace the token acts in, and list the tools it can call.
`mcp:write`	Browser consent only. Write access across screening, risk, and identity verification. It never grants administration.
`screening:search`	Member. Run new searches against sanctions, PEP, and adverse media. Searches count against your organization’s usage.
`screening:read`	Member. Read search results, profiles, potential matches, and profile comments.
`screening:write`	Member. Create and edit profiles, set profile and potential-match status, and add profile comments.
`risk:read`	Member + agent risk beta. Read risk assessments along with their tasks, subjects, and comments.
`risk:write`	Member + agent risk beta. Create and edit risk assessment tasks, subjects, and comments.
`idv:read`	Member + ID verification. Read identity verification sessions and the status of each check.
`idv:write`	Member + ID verification. Start, resend, and cancel identity verification sessions.
`admin:team`	Admin. Read who belongs to this organization and the team role each person holds.
`admin:config_read`	Admin. Read workspace and organization configuration settings.
`admin:config_write`	Admin. Change workspace and organization configuration settings.
`offline_access`	Browser consent only. Stay connected without signing in again until access is withdrawn.

Browser consent only means a client can request the scope during browser sign-in, but it can never be added to a personal access token. mcp:write does not bypass anything: a write it covers still needs whatever entitlement the specific scope needs, so it reaches risk assessments only in an organization that has the agent risk assessment beta, and identity verification only where ID verification is enabled.

How scopes are narrowed

Minerva advertises the whole catalog above, and most agents request everything a server advertises on first login. That is expected and is not an error. Minerva grants the intersection of:

The scopes the agent requested
The scopes the tenant token policy allows
The scopes your team role and your organization’s entitlements permit

The token response reports the scopes that were actually granted. A Member in an organization that allows only screening scopes therefore ends up with a working connection that has screening tools and no administration tools. That is not a failed login. Check the granted scope list, not the requested one, when an expected tool is missing. A few entitlements are granted per workspace rather than per organization (today the agent risk assessment beta), and the scopes that need one behave differently depending on the token’s reach. A token that acts in every workspace always carries risk:read and risk:write if the policy and your role allow them. There is no single workspace to check the beta against when the token is issued, so the check happens on each call instead, against the workspace that call names. The same token therefore succeeds in a workspace that has the beta and is refused in one that does not. A token pinned to one workspace carries them only if that workspace holds the beta. So pinning does not get you more capability: it gets you less, and more predictably. The reason to pin is blast radius, not reach. Refused risk calls are therefore about the workspace you are calling into, not about the token. See Troubleshooting.

Troubleshooting

In the browser

Symptom	Cause and fix
Personal access tokens are disabled for this organization	Your administrator has not enabled Hosted MCP access. It is off by default. Someone with the Admin role or above turns it on under Configuration > Authentication > Hosted MCP access.
Personal access tokens require the … role or higher	Your team role is below the policy’s Minimum team role. Ask an Admin to lower the minimum, or to raise your team role.
Nothing in this organization’s token policy is available to you	The policy allows only scopes your role or your organization’s products cannot carry. An Admin adds scopes you can hold, or Minerva enables the missing entitlement.
The consent link fails before you can approve	The authorization request expired, or was already used because the login ran twice. Re-run the login command from the client so it starts a fresh request.
`429` with an empty response body (`server: awselb/2.0`, no content-type)	The edge rate limit: 100 requests per 300 seconds per source IP, one bucket shared by `/oauth/register`, `/oauth/token`, and `/oauth/revoke`, any method. Blocked attempts still count toward the rate, so a tight loop that keeps re-flooding restarts the clock, and a slow one tells you nothing; left alone, the block lifts once the rate falls below the limit. Stop sending requests to those three paths for about five minutes, plus a short detection lag, then try once; an occasional attempt does not restart the clock. The limit can also engage a few minutes after you exceed it, so the block may appear later than the burst that caused it.
`429` with a JSON error body and an `x-request-id`	The application registration limit: 20 client registrations per source IP per hour, and it covers only `/oauth/register`. Reuse your existing client registration, or wait out the hour.
Codex login fails with Authorization server response missing required issuer after the browser approval	A codex-cli bug, not a Minerva one: stable clients (0.146.0 or earlier) enforce the issuer requirement without reading the issuer from their own callback, and Minerva correctly sends it. Use a personal access token, or codex-cli 0.147.0-alpha.2 or later (currently the npm `alpha` channel).

Both rate limits key on your source IP, so a shared office or CI egress can trip them without anyone misbehaving. Neither one touches existing tokens, tool calls, discovery, or the authorization step itself: those keep working while new logins are throttled. A greyed-out Create token button has two different causes, and the message on screen tells you which. This one shows Personal access tokens are disabled for this organization, meaning nobody here has hosted MCP access yet: And this one shows Personal access tokens require the … role or higher, meaning the organization has enabled it but your own team role sits below the minimum the policy sets, which is a different fix: And this is the same organization from the admin’s side, where the switch is turned off: A browser that opens the consent URL without a usable authorization request gets one of two screens, and which one you get tells you what went wrong. If the request ID is well formed but no longer good (the link expired, or it was already used because the login ran twice), you get the invalid-request screen. Re-run the login command from the client so it starts a fresh request. If there is no request ID at all, or a malformed one (a hand-typed URL, or a link truncated in a chat message), you get an install landing page instead. It repeats the endpoints and carries copy-paste snippets for some clients, but it cannot complete a login on its own: the commands earlier in this guide are the authoritative set.

From an agent call

The three refusal codes an agent can meet (validation_error, workspace_forbidden and entitlement_required) are authorization outcomes, not transport failures. Minerva returns them as ordinary MCP tool results: HTTP 200 with isError: true, and the code, the message, and a retryable flag in the JSON inside content[0].text. A 401 therefore means authentication failed, while these mean the call was understood and refused. validation_error and entitlement_required are never retryable, and neither is a genuine workspace_forbidden refusal. The one retryable case is the service-problem form of workspace_forbidden, which says so in its message and sets retryable: true.

Symptom	Cause and fix
No Minerva tools at all, and no error	The client never connected, so no scope change will bring the tools back. On a personal access token using `bearer_token_env_var`, the usual cause is that the variable is not set in the environment the agent itself runs in. Check it there rather than in the shell you ran `codex mcp add` from. This is almost never downscoping: any token that carries `mcp:read` keeps `whoami` and `list_tool_permissions`, so if even those two are missing, scopes are not what removed them.
Some Minerva tools, but not the one you expected	Downscoping: that scope was requested but not granted. Compare the granted scopes against the policy, your role, and your entitlements. If the policy is narrower than the work genuinely needs, ask an admin to widen it for that scope rather than in general.
`401` after the connection previously worked	The access token expired, and refresh only happens if `offline_access` was granted. Re-run the client’s login command. For a personal access token, create a new one and update your secret.
The agent sees no data, or not the data you expected	Check the token’s reach. A pinned token acts only in the workspace it names, and a tool argument naming a different one is refused rather than honoured. A tenant-wide token acts wherever the call says, so look at the workspace the call named.
this token is not bound to a workspace, so workspace_id is required …	`validation_error`. The token acts in every workspace, so it cannot infer a target: each call has to name one. Expect this to be the first error an agent hits with a tenant-wide token, because nothing tells a model to pass a workspace until something does. `list_workspaces` is deliberately callable without a workspace so the agent can discover the ids, then retry with one named.
workspace_id does not match the workspace this token is bound to …	`validation_error`. The token is pinned to one workspace and the call named a different one, which Minerva refuses rather than honours. Omit `workspace_id` so the pin applies, or use a token that is not bound to a single workspace.
workspace_id must be a valid workspace identifier …	`validation_error`. The call named something that is not shaped like a workspace id at all. The usual case is a model inventing one. Call `list_workspaces` and pick a real id.
workspace `<ID>` is not available to this token …	`workspace_forbidden`, not retryable. The named workspace is not one this token can act on. Minerva answers unknown, archived, and other-tenant workspaces identically on purpose, so this does not tell you which. Call `list_workspaces` to see what the token can reach. Retrying the same call gets the same answer.
workspace access could not be verified just now; this is a service problem, not a refusal …	`workspace_forbidden`, retryable. Minerva could not reach the entitlement service, so nothing was learned about the workspace either way, and the payload sets `retryable: true`. Retry the call; if it persists, the problem is on Minerva’s side, not the token’s.
agent risk assessment … is not enabled for workspace `<ID>`	`entitlement_required`. The agent risk assessment beta is granted per workspace, and Minerva checks it on each call against the workspace that call names. The token is not the problem, and the same token can call the tool in a workspace that has the beta. Confirm the beta is enabled on that workspace, or direct the call at one that has it.
The same not-enabled message on every workspace you try	Also `entitlement_required`. A tenant-wide token is issued `risk:read` and `risk:write` without a workspace to check the beta against, so it can carry them in an organization where no workspace currently has it: most often one that had it, had an admin allow the scopes, and later lost it. The token is not broken. Ask an admin to confirm the beta is still enabled where you need it.
An application API key is rejected on the MCP endpoints	Application keys are never accepted on MCP, by design. Use the browser login or a personal access token instead.

On opencode, two commands help isolate an authorization problem:

# OAuth-capable servers and their auth status
opencode mcp auth list

# debug the OAuth connection for one server
opencode mcp debug minerva

Best practices

Use https://mcp.gominerva.com/mcp/readonly for any agent that does not need to write, instead of relying on scopes alone
Grant one connection per purpose rather than one broad connection reused everywhere, so revoking an agent does not disturb the others
Bind tokens to a single workspace unless an automation genuinely spans all of them
Keep the tenant policy as the ceiling you actually intend, and widen it in response to real workflows rather than in advance
Prefer the browser login for people, and reserve personal access tokens for automations that truly cannot open a browser
Store personal access tokens in a secrets manager, never in source control or in an agent configuration file committed to a repository
Schedule rotation before the 90-day ceiling rather than discovering it when a pipeline fails
Review the token table periodically and revoke tokens whose last-used timestamp shows they are no longer needed
Remember that an agent inherits its authorizer’s permissions, so review team roles when someone changes job

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Identity Verification - Endpoints

Before you begin

Key concepts

The Minerva MCP server

Connect your coding agent

Step 1: Register the server

Step 3: Approve the request

Personal access tokens

Step 1: Set the environment variable

Step 2: Register the server with a bearer token

Step 3: Verify the connection

When to prefer a token over the browser flow

Admin enablement

Scopes

How scopes are narrowed

Troubleshooting

In the browser

From an agent call

Best practices

​Before you begin

​Key concepts

​The Minerva MCP server

​Connect your coding agent

​Step 1: Register the server

​Step 2: Sign in

​Step 3: Approve the request

​Personal access tokens

​Step 1: Set the environment variable

​Step 2: Register the server with a bearer token

​Step 3: Verify the connection

​When to prefer a token over the browser flow

​Admin enablement

​Scopes

​How scopes are narrowed

​Troubleshooting

​In the browser

​From an agent call

​Best practices

Before you begin

Key concepts

The Minerva MCP server

Connect your coding agent

Step 1: Register the server

Step 2: Sign in

Step 3: Approve the request

Personal access tokens

Step 1: Set the environment variable

Step 2: Register the server with a bearer token

Step 3: Verify the connection

When to prefer a token over the browser flow

Admin enablement

Scopes

How scopes are narrowed

Troubleshooting

In the browser

From an agent call

Best practices