> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/guides/integrating-with-ess-mcp.md).

# Integrating an AI Agent with ESS using MCP

{% hint style="success" %}
Added in version 3.0.0. Updated for ESS 3.5.0.
{% endhint %}

This guide walks through connecting an AI agent or other application to the ESS [MCP Service](https://docs.inrupt.com/ess/latest/services/service-mcp/), which lets it request access to users' data and read that data through Model Context Protocol (MCP) tools.

## Overview

A typical MCP client workflow is:

1. Obtain an [ESS Access Token](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens) for the MCP Service from the [Platform Management service](https://docs.inrupt.com/ess/latest/services/service-platform-management/).
2. Connect to the MCP Service with an MCP client, sending the token on every request.
3. Use the MCP tools to request access to a user's resources, wait for the user to approve, and then read the resources.

The token identifies an ESS agent. Every MCP tool acts as that agent: it can only see the Access Requests that agent created and the Access Grants issued to it.

## Prerequisites

### For the ESS operator

Before a developer can obtain a token for the MCP Service, an ESS operator must set up the following. Without it, token requests fail, for example with **`invalid_client`**.

* An [ESS 3.5.0 or later](https://docs.inrupt.com/ess/latest/) deployment with the MCP Service. Its base URL is `https://mcp.<ESS Domain>/api`.
* For an AI agent:
  * The host of the agent's client ID on the [domain allow list](https://docs.inrupt.com/ess/latest/installation/customize-configurations/customization-security/manage-cimd-client-domains).
  * An active agent account [bound to the client ID](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens#step-3-bind-the-client-id-to-an-agent-account).
* For an application acting for a signed-in user:
  * The user's Identity Provider [trusted by ESS](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens#trusted-identity-provider-configuration).
  * The user's Identity Provider identity [mapped to their ESS account](https://docs.inrupt.com/ess/latest/services/service-platform-management/platform-management-api#set-identity-mappings).

### For the developer

* An MCP client that supports [MCP protocol](https://modelcontextprotocol.io/specification/2026-07-28) revision **`2026-07-28`**. The MCP Service refuses earlier revisions.
* For an AI agent: a Client ID Metadata Document published at an HTTPS URL, and the private key that signs the client assertion. See [Step 1](#ai-agents-client-credentials-with-cimd).
* For an application acting for a signed-in user: a way to sign the user in with their Identity Provider and get their ID token. See [Step 1](#applications-acting-for-a-signed-in-user-token-exchange).

## Step 1: Get an ESS Access Token

An application can obtain a token in one of two ways. In both cases, request the token for the MCP Service by setting **`resource`** to its URL, and request the [scopes](https://docs.inrupt.com/ess/latest/services/service-mcp/#scopes) for the tools the application needs.

{% hint style="warning" %}
A token without the required scope cannot call a tool.
{% endhint %}

### AI agents: Client Credentials with CIMD

An AI agent that acts on its own behalf authenticates with a [Client ID Metadata Document (CIMD)](https://docs.inrupt.com/reference/glossary.md#client-id-metadata-document-cimd) and the OAuth 2.0 `client_credentials` grant. Before it can obtain a token, an ESS operator must add the agent's host to the domain allow list and bind its client ID to an agent account. See [Client Credentials with CIMD](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens#client-credentials-with-cimd) for how to publish the document and create the client assertion.

To request a token, send a `client_credentials` request to the Platform Management service's token endpoint. This example uses a signed client assertion as proof of the agent's identity:

```bash
curl -X POST https://platform.<ESS Domain>/access/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=https://agent.example.com/client.json" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=<signed client assertion>" \
  --data-urlencode "resource=https://mcp.<ESS Domain>" \
  --data-urlencode "scope=mcp:access-request:write mcp:access-request:read mcp:access-grant:read mcp:storage:read"
```

### Applications acting for a signed-in user: Token Exchange

An application acting for a user who signs in with your Identity Provider exchanges the user's token for an ESS Access Token. See [Token Exchange](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens#token-exchange).

To request a token, send a token exchange request to the Platform Management service's token endpoint. This example presents the user's ID token from your Identity Provider as the subject token:

```bash
curl -X POST https://platform.<ESS Domain>/access/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=<idp-id-token>" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  --data-urlencode "resource=https://mcp.<ESS Domain>" \
  --data-urlencode "scope=mcp:access-request:write mcp:access-request:read mcp:access-grant:read mcp:storage:read"
```

A successful response contains the ESS Access Token in **`access_token`**, and its lifetime in seconds in **`expires_in`**.

## Step 2: Connect to the MCP Service

Send the ESS Access Token in the **`Authorization`** header, and the MCP protocol revision in the **`Mcp-Protocol-Version`** header, of every request to the MCP Service:

```http
Authorization: Bearer <ESS Access Token>
Mcp-Protocol-Version: 2026-07-28
```

The MCP Service supports only protocol revision `2026-07-28`, over the Streamable HTTP transport. This revision is stateless: there is no `initialize` handshake or session, and every request is a **`POST`** to the base URL. An MCP client that supports this revision sends the **`Mcp-Protocol-Version`** header itself. If you build requests by hand, include it: a **`POST`** without the header, or with a different revision, is refused with **`400`**.

An MCP client that follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) can also discover how to get a token: a request without a token is answered **`401`** with a challenge that points to the MCP Service's [protected resource metadata](https://docs.inrupt.com/ess/latest/services/service-mcp/#protected-resource-metadata).

## Step 3: Use the MCP Tools

For each tool's parameters and responses, see the [MCP Service](https://docs.inrupt.com/ess/latest/services/service-mcp/) reference.

1. **Check for an existing Access Grant.** Use `hasMatchingAccessGrant` to check whether the user has already granted the agent access to the resource. Set `dataSubject` to the identifier of the user who owns the resource. If so, go to step 4.
2. **Request access.** Use `requestAccess` to create an Access Request for the resource, with `dataSubject` set to the same identifier. It returns the Access Request URL.
3. **Wait for approval.** The user reviews the Access Request in a separate application; it cannot be approved through the MCP Service. Use `checkAccessRequestStatus` with the Access Request URL until its status changes from `pending` to `granted`, `denied` or `canceled`.
4. **Read the resource.** Use `getResource` with the resource URL. ESS checks that the agent can read the resource, for example through an Access Grant issued to it. The result is an MCP embedded resource: read the content from `resource.text`, and its URL, content type and ETag from `resource.uri`, `resource.mimeType` and `resource._meta.etag`.

For example, a successful `getResource` call returns:

```json
{
  "content": [
    {
      "type": "resource",
      "resource": {
        "uri": "https://storage.example.com/01JXYZ1234ABCDEF5678GHIJ90/sc/01JABC1234DEF5678GHI90JKLM",
        "mimeType": "application/json",
        "text": "{\"balance\": 1250.00, \"currency\": \"EUR\"}",
        "_meta": {
          "etag": "\"a1b2c3d4\""
        }
      }
    }
  ],
  "isError": false
}
```

## Try It with MCP Inspector

To try the MCP tools without building a client, use a version of [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) that supports protocol revision `2026-07-28`, such as 2.12.0.

MCP Inspector cannot obtain the ESS Access Token for you. Its built-in sign-in uses a browser authorization flow, which needs an authorization endpoint, and ESS has none. Get a token with the request in [Step 1](#step-1-get-an-ess-access-token) and give it to MCP Inspector in a header.

{% hint style="info" %}
ESS Access Tokens are short-lived (5 minutes by default). When the token expires, request a new one and reconnect.
{% endhint %}

1. Save the following configuration in an `mcp.json` file:

   ```json
   {
     "mcpServers": {
       "ess": {
         "type": "streamable-http",
         "url": "https://mcp.<ESS Domain>/api"
       }
     }
   }
   ```
2. Start MCP Inspector with this configuration, selecting the `modern` protocol era, which is the one that implements revision `2026-07-28`. The default era makes MCP Inspector send an `initialize` request, which the MCP Service does not implement:

   ```bash
   npx @modelcontextprotocol/inspector --cli --protocol-era modern \
     --config mcp.json --server ess \
     --header "Authorization: Bearer <ESS Access Token>" \
     --method tools/list
   ```

   This lists the MCP Service's tools. To call a tool, use `--method tools/call --tool-name <tool> --tool-arg <name>=<value>`.

## Errors

| Situation                                                                                 | What to do                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`401`** response from the MCP Service                                                   | The token is missing, invalid or expired. Obtain a new token and retry.                                                                                                                                              |
| **`403`** response with an **`insufficient_scope`** challenge                             | The token lacks the scope the tool requires. Obtain a token that includes the scope named in the challenge, and retry.                                                                                               |
| **`invalid_client`**, **`invalid_scope`** or **`invalid_target`** from the token endpoint | The client could not authenticate, or requested a scope or resource it is not allowed. See [Error Responses](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens#error-responses). |
| A tool returns an error                                                                   | The tool could not complete, for example because the resource does not exist or the agent cannot read it. The error message explains why.                                                                            |

## Best Practices

1. **Request only the scopes you need.** A client that only manages Access Requests does not need `mcp:storage:read`.
2. **Check for existing Access Grants first** to avoid creating duplicate Access Requests.
3. **Give a clear purpose** in Access Requests, to help users decide.
4. **Poll with backoff** while waiting for approval, because approval is done by a person.
5. **Renew tokens before they expire.** ESS Access Tokens are short-lived (5 minutes by default) and no refresh token is issued; use `expires_in` to request a new token in time.
6. **Use** [**canonical resource URIs**](https://docs.inrupt.com/ess/latest/identifiers#canonical-uris) (the `/sc/` form) for durable references.
7. **Keep tokens and keys secret.** Never expose them in client-side code or logs.

## Additional Resources

* [MCP Service](https://docs.inrupt.com/ess/latest/services/service-mcp/)
* [Access Tokens](https://docs.inrupt.com/ess/latest/services/service-platform-management/access-tokens)
* [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2026-07-28)
