> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/federation/mcp-server.md). # Connect AI assistants through the MCP server Deploy the OpenIAM MCP server, publish it through the Access Gateway, decide which roles may use it, and connect Claude.ai, Claude Code or another MCP client that signs users in with OpenIAM. ## What this is, and when you need it The OpenIAM MCP server lets an AI assistant answer questions from OpenIAM data on behalf of the person using it. MCP is the Model Context Protocol, the protocol Claude and other assistants use to call tools on a server. The server offers 17 read-only tools: who the user is, users and organizations, the access a user holds, the request catalog, the user's own requests, approvals and certifications, and an audit search for administrators. Every list of them, with arguments and results, is in [MCP tools, errors, properties and limits](/administration-guide/federation/mcp-server/mcp-server-reference.md). An assistant acts as the signed-in user. The user signs in to OpenIAM through the identity provider (IdP) with OAuth 2.0, the token names both the user and the assistant, and every tool applies the same checks Webconsole and SelfService apply for that user. **An assistant acting for a user never reads what that user could not read in Webconsole or SelfService.** Two things sit on top of that. Every client has an **agent record** in the non-human identity inventory, which names a sponsor, can be suspended in one action, and lets an agent act alone, with no person behind it, as a governed service user: [Govern AI agents as non-human identities](/administration-guide/federation/mcp-server/mcp-agents.md). And every tool call can be a policy decision that narrows what a person or an agent may call, and masks what comes back: [Decide MCP tool calls with policies](/administration-guide/federation/mcp-server/mcp-policies.md). You are not in the right place if: * You are registering an ordinary web or mobile application. Use [OAuth 2.0 and OpenID Connect](/administration-guide/federation/oauth-and-oidc.md). * You want an AI agent to act with its own identity and no person behind it. Register it as described in [Govern AI agents as non-human identities](/administration-guide/federation/mcp-server/mcp-agents.md), then come back here for the gateway and the scopes. * You want an assistant to change data. There are no write tools in 2026.10.2. ## At a glance | | | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | Users who add `https:///mcp` to Claude, sign in with OpenIAM, and get answers limited to what their own entitlements allow | | **Where** | The `mcp` container image and Helm chart; **Access Control → Content Providers** for the gateway patterns; **Access Control → Resources** for the scope grants; `idp.ui.properties` for which clients may register themselves | | **You need first** | 2026.10.2 on the IdP, the enterprise service bus (ESB) and Webconsole, with the database migration applied and the authorization graph rebuilt; HTTPS on the public host name | | **Takes** | An hour, most of it the gateway patterns and the first sign-in | | **Reversible** | Yes — see [Roll it back](#roll-it-back) | ## Before you begin * **Upgrade every component to 2026.10.2 first.** The migration seeds the four MCP scopes and their role grants, and the grants are written straight into the entitlement tables. Rebuild the authorization graph once afterwards, as described in [Rebuild the authorization graph](/administration-guide/operations/rebuild-the-authorization-graph.md). Until then no user is entitled to an MCP scope and every sign-in ends without one. * **Serve the public host name over HTTPS** with a certificate the clients trust. Claude Code refuses to send the authorization code to a token endpoint over plain HTTP unless the host is `localhost` or a loopback address, so a plain-HTTP deployment fails after the user has already signed in. * **Open the network paths.** Claude.ai connects from Anthropic's servers, not from the user's browser, so a web application firewall (WAF) in front of OpenIAM must admit Anthropic's egress range `160.79.104.0/21` to both the MCP host and the IdP host. The IdP itself must reach `https://claude.ai` over HTTPS, because it fetches the client's metadata document from there on the first sign-in. Claude Code runs on the user's machine and needs nothing beyond what the user's browser already reaches. * **Name the owner of self-registered agents.** Set `org.openiam.oauth.cimd.agent.owner` in `idp.ui.properties` to the user ID of an administrator account. The IdP creates an AI Agent record in the non-human identity inventory for every client that registers itself, with that account as owner and sponsor, and refuses to register a client while the property is empty. ## Deploy the server The server is a separate web application, `mcp.war`, that talks to the rest of OpenIAM over RabbitMQ and Redis like the other user interface (UI) applications. It listens on port 8080 inside its container and serves `/mcp` and `/.well-known/oauth-protected-resource` at the root of the host, not under an application prefix. {% tabs %} {% tab title="Kubernetes" %} 2026.10.2 publishes an `mcp` Helm chart next to the `idp` chart. The deployment's Terraform configuration does not install it yet in this release, so install it with Helm into the namespace that runs the IdP, reusing the IdP release's values for Redis, RabbitMQ, Vault and the image registry, without the IdP's own Java options: {% code overflow="wrap" %} ```bash helm get values -idp -n -o yaml > mcp.values.yaml helm upgrade --install -mcp oci:///mcp --version 2026.10.2 -n -f mcp.values.yaml --set openiam.replicas=2 --set openiam.javaOpts="" ``` {% endcode %} The chart creates a cluster-internal service named `mcp` on port 8080, the name the OpenIAM nginx forwards to, two replicas by default, a readiness probe on `/actuator/health` and Prometheus scrape annotations for `/actuator/prometheus`. The server's own settings sit under `openiam.mcp.properties` in the chart values; every key ships empty, which keeps the default built into the server. For example, to allow a browser-based client: {% code overflow="wrap" %} ```yaml openiam: mcp: properties: org.openiam.mcp.allowed.origins: "https://assistant.example.com" ``` {% endcode %} {% endtab %} {% tab title="Docker Compose" %} 2026.10.2 publishes an `mcp` image in the `openiam_service` namespace, built on the same `spring-boot-base` image as the IdP. Run it as a service named `mcp` in the stack that runs the other UI containers, with the same environment and volumes as the `idp` service. In the OpenIAM Docker Compose deployment that stack is `ui`, so other stacks, the gateway among them, reach the server as `ui_mcp`. The nginx in front of the UI containers must forward `/mcp` and `/.well-known/oauth-protected-resource` to `ui_mcp:8080`, as the next section explains. Put server settings in `conf/properties/mcp.ui.properties` under the shared configuration volume, one `key=value` per line, and restart the container after a change. {% endtab %} {% tab title="RPM" %} The RPM packages of 2026.10.2 do not include the MCP server. Run it as a container next to the RPM installation, or wait for a release that packages it. {% endtab %} {% endtabs %} Leave `org.openiam.mcp.resource.url` and `org.openiam.mcp.issuer.url` empty unless the server is reached under more than one host name. Empty values derive `https:///mcp` and `https:///idp/oauth2` from each request, which is also what the IdP derives, so the two always agree. Every property is in [the reference](/administration-guide/federation/mcp-server/mcp-server-reference.md#properties). ## Publish it through the Access Gateway The gateway routes by Uniform Resource Identifier (URI) pattern, and four public patterns carry the MCP traffic. They are public because the MCP server answers its own sign-in challenge: an MCP client starts signing in only on an HTTP 401 that carries a `WWW-Authenticate` header naming the server's metadata, and the gateway's own 401 page has no such header. The server checks every token itself. {% stepper %} {% step %} Make sure the nginx in front of the UI applications forwards the MCP paths. The four MCP patterns have no application server of their own, so the gateway sends them to the content provider's servers: the same OpenIAM nginx that routes `/webconsole` and `/selfservice`. That nginx must forward `/mcp` and `/.well-known/oauth-protected-resource` to the MCP server, and `/.well-known/oauth-authorization-server/idp/oauth2` to the IdP's `/idp/oauth2/.well-known/oauth-authorization-server`. The OpenIAM nginx image of 2026.10.2, which the Kubernetes chart runs, forwards to `mcp:8080`; the OpenIAM Docker Compose deployment's own nginx configuration forwards to `ui_mcp:8080`. A customised nginx configuration needs the three locations added by hand. {% endstep %} {% step %} Create the patterns. A content provider set up for the first time on 2026.10.2 gets them automatically. On an existing content provider, open **Access Control → Content Providers**, open the provider, and press **Create default URI patterns**. That button also re-applies the shipped flags to every other default pattern, so export the provider first if you customised any; the warning is in [Create default URI patterns](/administration-guide/access/content-providers-and-uri-patterns/content-provider-reference.md#create-default-uri-patterns). To add the patterns by hand instead, use the values in the table below. {% endstep %} {% step %} Wait for the caches. The URI-federation cache refreshes every 30 seconds and the content-provider cache every five minutes, so allow five minutes before you test. {% endstep %} {% endstepper %} | URI pattern | Authentication rule | Cached | Application server | | ---------------------------------------------------- | ----------------------- | ------ | ------------------------------------------------------------------------------ | | `/mcp` | **Def. None Auth Rule** | 30 s | The content provider's own servers; the UI nginx forwards it to the MCP server | | `/.well-known/oauth-protected-resource` | **Def. None Auth Rule** | 1800 s | The content provider's own servers; the UI nginx forwards it to the MCP server | | `/.well-known/oauth-protected-resource/mcp` | **Def. None Auth Rule** | 1800 s | The content provider's own servers; the UI nginx forwards it to the MCP server | | `/idp/oauth2/.well-known/oauth-authorization-server` | **Def. None Auth Rule** | 1800 s | The content provider's own servers, like every `/idp` pattern | Clients look for the authorization server's metadata in up to three places, in order. The seeded patterns serve the last of them, `/idp/oauth2/.well-known/openid-configuration`, which every client falls back to. The first, `/.well-known/oauth-authorization-server/idp/oauth2`, has no seeded pattern, although the UI nginx answers it with the IdP's document. If a client stops at that request because the gateway answers it with the sign-in page, add a pattern for it with **Def. None Auth Rule** so the request reaches the nginx. ## Decide who may use it Each tool belongs to one of four OAuth scopes, and a user receives a scope only through an entitlement to its resource. The scopes are resources of type `OAUTH_SCOPE` and, unlike every other OpenIAM scope, they are not public, so the entitlement is the control. Which users may use an assistant at all, and for what, is therefore an ordinary role-to-resource grant that shows up in the same screens, reports and certification campaigns as every other entitlement. | Scope | Tools | Granted by the migration to | | --------------------------- | ------------------------------------------------------------------------- | ------------------------------ | | `openiam:mcp:identity:read` | `whoami`, users, direct reports, organizations | End User, Super Security Admin | | `openiam:mcp:access:read` | the access a user holds, access checks, entitlements, the request catalog | End User, Super Security Admin | | `openiam:mcp:workflow:read` | the user's own requests, approvals and certifications | End User, Super Security Admin | | `openiam:mcp:audit:read` | `search_audit_events` | Super Security Admin | To change the grants, open **Access Control → Resources**, search for the scope name, and change the roles on the resource's entitlements, as for any resource. To keep assistants away from most users, remove the three read scopes from End User and grant them to a smaller role instead. Two more checks apply beneath the scopes. A tool that reads another user, such as `get_user`, makes the same policy-based access control (PBAC) decision Webconsole makes for its user screen, the `VIEW_USER` action described in [Grant access to user administration](/administration-guide/identities/grant-user-administration.md); the request names `mcp` as the invoking system. Searches are limited to the organizations and delegation filters Webconsole applies to the same user. A third check can sit above both. With `org.openiam.mcp.pbac.mode` set to `shadow` or `enforce`, every tool call is a PBAC decision on the tool, the caller and the target, and seven shipped policies record from the first call what they would decide. A person is allowed when no policy applies; an agent acting alone is refused. The vocabulary, the modes and the order to roll them out in are in [Decide MCP tool calls with policies](/administration-guide/federation/mcp-server/mcp-policies.md). The server advertises only the three read scopes, so the consent page stays short. The audit scope is requested the first time the user asks for audit data: the server answers that call with HTTP 403 `insufficient_scope`, Claude asks the user to sign in again for the extra scope, and the IdP grants it only to a user entitled to it. ## Connect Claude The IdP registers Claude's OAuth client itself on the first sign-in, from the client metadata document Claude publishes on `claude.ai`, so you register nothing in advance. The origins allowed to do so are in `org.openiam.oauth.cimd.allowed.origins` in `idp.ui.properties`, which ships as `https://claude.ai`; [Let an MCP client register itself](/administration-guide/federation/oauth-and-oidc.md#let-an-mcp-client-register-itself) explains the mechanism and how to turn it off. The same sign-in creates the client's agent record, an AI Agent identity owned and sponsored by the account in `org.openiam.oauth.cimd.agent.owner`, Active unless `org.openiam.oauth.cimd.agent.approval` is `required`, in which case the sign-in ends with `access_denied` until an administrator approves the record. What the record holds, and what suspending it does, is in [How a Claude client gets its record](/administration-guide/federation/mcp-server/mcp-agents.md#how-a-claude-client-gets-its-record). ### Claude.ai {% stepper %} {% step %} In Claude, open **Settings → Connectors** and choose **Add custom connector**. {% endstep %} {% step %} Enter a name and the URL `https:///mcp`, then choose **Add**. {% endstep %} {% step %} Choose **Connect**. Claude opens the OpenIAM sign-in page; the user signs in as usual, including any multi-factor step their authentication policy requires. {% endstep %} {% step %} Read the consent page, then choose **Allow**. It names the client, shows `claude.ai` as the host the client's metadata document came from, and lists the three read scopes. {% endstep %} {% endstepper %} ### Claude Code Run this once on the user's machine, then start Claude Code, run `/mcp`, select `openiam` and choose **Authenticate**. `claude mcp login openiam` does the same from the shell: {% code overflow="wrap" %} ```bash claude mcp add --scope user --transport http openiam https:///mcp ``` {% endcode %} The browser opens the same sign-in and consent pages. The consent page warns that every callback address is local: Claude Code receives the answer on a port of the user's own machine, so the warning is expected here. When the host's certificate comes from a private certificate authority, start Claude Code with `NODE_EXTRA_CA_CERTS` pointing at that authority's certificate. ### A client without a metadata document A client that cannot publish a metadata document needs a client registered by hand. The register-agent wizard described in [Govern AI agents as non-human identities](/administration-guide/federation/mcp-server/mcp-agents.md) creates such a client together with its agent record; to register one yourself instead, follow [Register an OAuth client](/administration-guide/federation/oauth-and-oidc.md#register-an-oauth-client) with these values, then give the user the client ID, and the secret if you set one. In Claude.ai they go under **Advanced settings** of the custom connector. | Field | Value | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization Grant Flow** | `AUTHORIZATION_CODE_PKCE`, with or without a client secret, or `AUTHORIZATION_CODE` with a secret, for a client that signs people in. `CLIENT_CREDENTIALS` only for an agent that acts alone, bound to an AI Agent identity with a service user as described in [Govern AI agents as non-human identities](/administration-guide/federation/mcp-server/mcp-agents.md). The MCP server refuses tokens of any other flow | | **Redirect URL** | The client's callback, for Claude.ai `https://claude.ai/api/mcp/auth_callback` | | **Default Scopes** | The four `openiam:mcp:*:read` scopes | | **Use Refresh Token** | On, so the user does not sign in again every hour | ## Verification Run these from any machine that reaches the public host. The first three need no token. {% code overflow="wrap" %} ```bash curl -si -X POST https:///mcp | grep -i '^HTTP\|^www-authenticate' curl -s https:///.well-known/oauth-protected-resource/mcp curl -s https:///idp/oauth2/.well-known/openid-configuration ``` {% endcode %} | Check | Correct result | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The challenge | `HTTP/1.1 401` and `WWW-Authenticate: Bearer error="invalid_token", …, resource_metadata="https:///.well-known/oauth-protected-resource/mcp", scope="openiam:mcp:identity:read openiam:mcp:access:read openiam:mcp:workflow:read"`. The gateway's HTML 401 page instead means the patterns are missing | | The protected-resource document | JSON with `"resource":"https:///mcp"`, `authorization_servers` holding `https:///idp/oauth2`, and the three read scopes | | The authorization-server document | `client_id_metadata_document_supported` is `true`, and `token_endpoint_auth_methods_supported` contains `none` | | A signed-in call | Claude lists 17 tools, and asking it "who am I in OpenIAM?" calls `whoami` and returns the signed-in user | | The audit trail | **Administration → Log Viewer** shows one `MCP_TOOL_CALL` event per tool call, with the user, the client, the tool and the outcome. The attributes are listed in [the reference](/administration-guide/federation/mcp-server/mcp-server-reference.md#the-audit-event) | | The agent record | **Webconsole → Non-Human Identities → Inventory**, filtered to **Agents**, lists one AI Agent identity per client that has signed in, Active, owned by the account the property names | To list the tools without an assistant, use an access token the IdP issued to an MCP client: {% code overflow="wrap" %} ```bash curl -s https:///mcp -H 'Authorization: Bearer ' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` {% endcode %} ## When it goes wrong | Symptom | Likely cause | Resolution | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude.ai cannot connect and the IdP log shows no request from it | A WAF blocks Anthropic's egress range, or `/mcp` is not routed | Admit `160.79.104.0/21` to the MCP host and the IdP host; run the challenge check from outside the network | | `POST /mcp` answers the gateway's HTML 401 page, or 404 | The four patterns are missing, typically on a content provider seeded before 2026.10.2 | Press **Create default URI patterns**, or add the patterns by hand | | `POST /mcp` answers 502, 503 or nginx's 404 page while `/webconsole` works | The nginx in front of the UI applications does not forward `/mcp`: an image or configuration older than 2026.10.2, or a customised one. Or no MCP replica is ready | Deploy the 2026.10.2 nginx image, or add the three locations from [Publish it through the Access Gateway](#publish-it-through-the-access-gateway); check the pods' readiness | | Claude asks for a client ID and secret | The IdP does not advertise metadata-document registration, usually because `org.openiam.oauth.cimd.allowed.origins` is empty | Set it to `https://claude.ai` and restart the IdP | | `invalid_client` / `could not be registered from its metadata document` after sign-in | The IdP cannot reach `https://claude.ai`, or the client's origin is not allowed | Allow outbound HTTPS from the IdP to `claude.ai`; the IdP log names the rule that failed | | Registration fails and the IdP log names `org.openiam.oauth.cimd.agent.owner` | The property is empty, so the IdP cannot create the client's agent record | Set it to an administrator's user ID and restart the IdP | | Every sign-in after the first ends with `access_denied` | The ESB is older than 2026.10.2 and counts the user's consent against the wrong identity | Upgrade the ESB | | Claude Code signs in, then reports that the server needs authentication | The token endpoint is plain HTTP on a host that is not `localhost`; Claude Code refuses to send the code there | Serve the host over HTTPS | | 401 with `The access token was not issued for this resource` | The token carries no MCP scope: the user has no entitlement to the scopes, often because the graph was not rebuilt after the migration | Rebuild the authorization graph; check the user's roles against [Decide who may use it](#decide-who-may-use-it) | | 401 with `The access token was not obtained through a user authorization` | The token came from a password client, from Webconsole or another application that obtains its tokens without an authorization code, or from a client-credentials client that is not bound to an AI Agent identity with a service user | Bind the client as described in [Govern AI agents as non-human identities](/administration-guide/federation/mcp-server/mcp-agents.md); a password client is never admitted | | 401 with `The client is not registered as an agent`, or `The client's agent is pending approval`, `is suspended` or `has expired`; or `The access token is not valid` right after the agent was suspended | The client's agent record is missing while `org.openiam.mcp.agent.required` is `true`, is waiting for approval, was suspended or decommissioned, or has expired | See [When it goes wrong](/administration-guide/federation/mcp-server/mcp-agents.md#when-it-goes-wrong) on the agents page | | `search_audit_events` keeps answering 403 `insufficient_scope` after the user signs in again | The user is not entitled to `openiam:mcp:audit:read` | Grant the scope through a role, or accept that the user may not search the audit log | | A tool answers `NOT_PERMITTED` for another user | The `VIEW_USER` PBAC decision refused, or no policy applies to the request; or, in enforce mode, a tool policy refused, and the message names it | The same user is refused in Webconsole, or the policy is one of those in [Decide MCP tool calls with policies](/administration-guide/federation/mcp-server/mcp-policies.md); adjust the policy rather than the MCP server | | Every tool answers `NOT_PERMITTED` for an agent acting alone | The server enforces tool policies and none permits the agent | Promote `MCP-02` or write a permit; see [The no-policy rule](/administration-guide/federation/mcp-server/mcp-policies.md#the-no-policy-rule) | | Every tool answers `UNAVAILABLE` | The server enforces tool policies and the policy service does not answer | See [When the policy service is unreachable](/administration-guide/federation/mcp-server/mcp-policies.md#when-the-policy-service-is-unreachable) | | 429 with `Retry-After` | The user and client exceeded a rate limit | Wait, or raise the limits in [Properties](/administration-guide/federation/mcp-server/mcp-server-reference.md#properties) | | 403 `Origin not allowed` | A browser-based client sent an `Origin` that is not in `org.openiam.mcp.allowed.origins` | Add the origin; native clients such as Claude Code send none | | The consent page shows no buttons, or **Deny** signs the user out, right after an upgrade | The browser kept the previous release's scripts, which static assets allow for five days | Reload the page without the cache, or clear the browser cache | ## Roll it back {% stepper %} {% step %} Stop new connections. Remove `https://claude.ai` from `org.openiam.oauth.cimd.allowed.origins`, or empty it, and restart the IdP. {% endstep %} {% step %} Suspend the agents. Under **Webconsole → Non-Human Identities → Inventory**, filter to **Agents** and suspend each identity: its client's tokens are revoked at once, and the server refuses the client within a minute, the time it keeps an agent record. To remove a client for good, decommission its identity, then delete the row named ` (claude.ai)`, or the client you registered by hand, under **Access Control → Authentication Providers**; a client whose identity is not decommissioned cannot be deleted. {% endstep %} {% step %} Remove the scope grants from the roles if you want to keep the clients but stop every user. Once the change reaches the server, it refuses their tokens with 401. {% endstep %} {% step %} Delete the four patterns from the content provider, and uninstall the chart or stop the container. Setting `org.openiam.mcp.enabled=false` instead leaves the server running with no `/mcp` endpoint. {% endstep %} {% endstepper %} ## Related * [MCP tools, errors, properties and limits](/administration-guide/federation/mcp-server/mcp-server-reference.md) — the 17 tools, the error codes, every property, the audit event, the metrics, the limits and what 2026.10.2 does not do * [OAuth 2.0 and OpenID Connect](/administration-guide/federation/oauth-and-oidc.md) — client registration, and how MCP clients register themselves * [OAuth endpoints, grants, scopes and signing](/administration-guide/federation/oauth-and-oidc/oauth-and-oidc-reference.md) — the tenant metadata document, Client ID Metadata Documents and the `resource` parameter * [Access Gateway reference](/administration-guide/gateway/access-gateway-reference.md) — the seeded patterns and how the gateway routes * [Govern AI agents as non-human identities](/administration-guide/federation/mcp-server/mcp-agents.md) — the agent record every client has, and agents that act alone * [Decide MCP tool calls with policies](/administration-guide/federation/mcp-server/mcp-policies.md) — the policy decision on every tool call * [Manage non-human identities](/administration-guide/nhi.md) — the inventory the agent records live in *Applies to OpenIAM 2026.10.2. Last reviewed 22 October 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/administration-guide/federation/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.