> 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/ess/services/service-mcp.md).

# MCP Service

{% hint style="success" %}
Added in version 3.0.0
{% endhint %}

The Model Context Protocol (MCP) Service enables AI agents and applications to securely access personal data stored in ESS. It is an [MCP](https://modelcontextprotocol.io/) server that exposes ESS capabilities, such as requesting access to a user's data and reading resources, as MCP tools that an AI agent can call.

## Tools

The MCP Service exposes four MCP tools:

**Access management**

* [**`requestAccess`**](#requestaccess): Create an Access Request for a resource
* [**`checkAccessRequestStatus`**](#checkaccessrequeststatus): Check the status of an Access Request
* [**`hasMatchingAccessGrant`**](#hasmatchingaccessgrant): Check whether a matching Access Grant exists

**Resource management**

* [**`getResource`**](#getresource): Retrieve the content of a resource that the agent has access to

The MCP Service is an OAuth 2.0 protected resource. All tools require an ESS Access Token issued by the [Platform Management service](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md), presented on every request. See [Authentication](#authentication).

## Security Model

The MCP Service uses a layered security approach:

1. **ESS Access Tokens**: Clients authenticate with ESS Access Tokens issued by the [Platform Management service](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md). The MCP Service only accepts tokens issued for it.
2. **Agent identity**: Each token identifies an ESS agent. An AI agent can [authenticate as its own agent](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#client-credentials-with-cimd) using a Client ID Metadata Document, or a user's application can [exchange the user's Identity Provider token](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#token-exchange). The tools only act on behalf of, and only reveal information about, that agent.
3. **Scopes**: Each tool requires a specific scope in the token, so a client can be limited to the tools it needs. See [Scopes](#scopes).
4. **Access Grants**: Access to another user's data is mediated through Access Grants, which are W3C Verifiable Credentials. The agent requests access, the user approves it, and ESS checks the agent's access on every resource read. Revoking an Access Grant takes effect immediately.

## Use Cases

### AI Agent Resource Access

An AI agent needs to review a user's financial data in order to provide them with a loan estimate.

Flow:

1. The agent discovers the authorization server from the MCP Service's [protected resource metadata](#protected-resource-metadata), and obtains an ESS Access Token from the Platform Management service
2. Agent uses the `requestAccess` tool to create an Access Request for the user's bank statements
3. User reviews and approves the Access Request
4. Agent uses `checkAccessRequestStatus` to detect approval
5. Agent uses `hasMatchingAccessGrant` to verify the grant
6. Agent uses `getResource` to retrieve the bank statements

### Automated Data Processing

An automated service processes user data on a schedule:

1. Service authenticates and obtains an ESS Access Token
2. Service checks for existing access grants using `hasMatchingAccessGrant`
3. If grant exists, service retrieves and processes the data
4. If [resource read auditing](https://docs.inrupt.com/ess/services/service-pod-management/service-pod-storage.md#inrupt_storage_audit_resource_read_enabled) is enabled, ESS audits each resource access

## Base URL

By default, the MCP Service runs from:

```
https://mcp.<ESS Domain>/api
```

## Protocol Version

{% hint style="warning" %}
Changed in version 3.5.0. Earlier MCP protocol revisions, and the HTTP+SSE transport, are no longer supported.
{% endhint %}

The MCP Service supports MCP protocol revision [**`2026-07-28`**](https://modelcontextprotocol.io/specification/2026-07-28) only, 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 that carries the access token and an **`Mcp-Protocol-Version: 2026-07-28`** header.

Requests that do not follow this revision are refused:

| Request                                                                                               | Response                                                                                      |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| A **`POST`** without an **`Mcp-Protocol-Version`** header, such as an earlier revision's `initialize` | **`400`**, with a JSON-RPC error naming the supported revision                                |
| A **`POST`** with any other **`Mcp-Protocol-Version`**                                                | **`400`**, with an `UnsupportedProtocolVersion` JSON-RPC error listing the supported revision |
| Any other HTTP method on the base URL, such as **`GET`** or **`DELETE`**                              | **`405`**                                                                                     |
| Any path below the base URL, including the HTTP+SSE transport's `/api/sse` and `/api/messages`        | **`404`**                                                                                     |

Requests without a valid access token are answered with a [`401` challenge](#authentication-challenges) before any of these checks.

## Integration Guide

For a complete workflow example demonstrating how to build an MCP client that requests access to resources and retrieves content, see the [Integrating with ESS MCP](https://github.com/inrupt/docs-gitbook/tree/main/guides/integrating-with-ess-mcp.md) guide.

## Authentication

The MCP Service is an OAuth 2.0 protected resource, as described in the [MCP authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization). Its authorization server is the Platform Management service.

Clients present an ESS Access Token in the **`Authorization`** header of every request:

```http
Authorization: Bearer <ESS Access Token>
```

The MCP Service only accepts tokens that the Platform Management service issued, and whose **`aud`** claim includes the MCP Service's base URL (for example, `https://mcp.example.com`). Request a token for it by setting the **`resource`** parameter of the token request to that URL.

A client can obtain a token in either of two ways:

* **As its own agent**: AI agents and other applications that act on their own behalf authenticate with a Client ID Metadata Document and the `client_credentials` grant. See [Client Credentials with CIMD](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#client-credentials-with-cimd).
* **For a signed-in user**: An application exchanges the user's Identity Provider token. See [Token Exchange](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#token-exchange).

The token identifies an ESS agent. Every tool acts as that agent, and only reveals information about it: the Access Requests it created, and the Access Grants issued to it.

### Discovery

A client that does not yet have a token can discover how to get one:

1. Send a request without a token. The MCP Service responds **`401`** with a challenge that points to its protected resource metadata.
2. Read the [protected resource metadata](#protected-resource-metadata) to find the authorization server.
3. Read the authorization server's [metadata](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#authorization-server-metadata) to find its token endpoint.
4. Obtain a token, requesting the scopes the client needs, and retry.

### Protected Resource Metadata

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

The MCP Service publishes [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728).

| Field    | Value                                                               |
| -------- | ------------------------------------------------------------------- |
| Endpoint | **`https://mcp.{ESS Domain}/.well-known/oauth-protected-resource`** |
| Method   | **`GET`**                                                           |

```json
{
  "resource": "https://mcp.example.com",
  "authorization_servers": ["https://platform.example.com"],
  "scopes_supported": [
    "mcp:access-grant:read",
    "mcp:access-request:read",
    "mcp:access-request:write",
    "mcp:storage:read"
  ],
  "bearer_methods_supported": ["header"]
}
```

| Field                          | Description                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------ |
| **`resource`**                 | The MCP Service's identifier. Tokens must include it in their **`aud`** claim. |
| **`authorization_servers`**    | The Platform Management service, which issues tokens for the MCP Service       |
| **`scopes_supported`**         | The [scopes](#scopes) the tools require                                        |
| **`bearer_methods_supported`** | **`header`**: tokens are only accepted in the `Authorization` header           |

### Authentication Challenges

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

A request without a valid token is answered **`401`**, with a challenge that lists the scopes the tools use and points to the protected resource metadata:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", scope="mcp:access-grant:read mcp:access-request:read mcp:access-request:write mcp:storage:read", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"
```

A tool call whose token does not include the scope the tool requires is answered **`403`**, with an **`insufficient_scope`** challenge naming that scope. The client can obtain a token that includes the scope and retry the call. The response body also contains a tool error explaining the refusal.

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="mcp", error="insufficient_scope", scope="mcp:storage:read", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"
```

### Scopes

Each tool requires one scope:

| Tool                           | Required Scope                 |
| ------------------------------ | ------------------------------ |
| **`requestAccess`**            | **`mcp:access-request:write`** |
| **`checkAccessRequestStatus`** | **`mcp:access-request:read`**  |
| **`hasMatchingAccessGrant`**   | **`mcp:access-grant:read`**    |
| **`getResource`**              | **`mcp:storage:read`**         |

The scopes a client can obtain are configured on the Platform Management service. See [Access Tokens](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md#configuration).

## Access Management Tools

The access management tools refuse callers whose agent account is not active.

### `requestAccess`

Creates a new Access Request for a resource and its children. The request is stored as a Verifiable Credential and can be reviewed and approved by the Resource Owner.

#### Request Parameters

| Parameter         | Type   | Required | Description                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| **`resource`**    | String | Yes      | URL of the target resource to request access to           |
| **`permission`**  | String | Yes      | Access mode requested: only `read` is currently supported |
| **`dataSubject`** | String | Yes      | Identifier of the Resource Data Subject Agent             |
| **`purpose`**     | String | Yes      | URL describing the purpose of the Access Request          |

#### Response

The created Access Request URL.

Each call creates exactly one Access Request. Calling the tool again creates another Access Request.

#### Access Control

* The Access Request is attributed to the agent identified by the access token. The agent cannot create Access Requests on behalf of any other agent.
* The access token must include a **`client_id`** claim.

### `checkAccessRequestStatus`

Checks the current status of a previously created Access Request. This allows clients to monitor whether requests have been approved, denied, or remain pending.

#### Request Parameters

| Parameter              | Type   | Required | Description                        |
| ---------------------- | ------ | -------- | ---------------------------------- |
| **`accessRequestUrl`** | String | Yes      | URL of the Access Request to check |

#### Response

The Access Request status, i.e. one of:

* `pending`
* `granted`
* `denied`
* `canceled`

#### Access Control

* The agent can only check the status of Access Requests it created, and of Access Grants and Access Denials issued to it.
* For any other credential, the tool responds exactly as it does for a credential that does not exist: the status could not be determined. The response does not reveal whether the credential exists.

### `hasMatchingAccessGrant`

Verifies whether an Access Grant issued to the agent matches the specified criteria.

#### Request Parameters

| Parameter         | Type   | Required | Description                                                                                                                         |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **`resourceUrl`** | String | Yes      | URL of the target resource to check                                                                                                 |
| **`purposeUrl`**  | String | Yes      | URL describing the purpose for which the Access Grant was issued. Can be left blank (`""`) to match Access Grants with any purpose. |
| **`mode`**        | String | Yes      | Access mode to verify: only `read` is currently supported                                                                           |
| **`dataSubject`** | String | Yes      | Identifier of the Agent who issued the Access Grant                                                                                 |
| **`status`**      | String | Yes      | Access Grant status (`active`, `revoked`, or `expired`). Can be left blank (`""`), which defaults to `active`.                      |

{% hint style="info" %}
In this release, the tool requires **`purposeUrl`** and **`status`**, even though they can be blank. To leave either one unset, pass an empty string (`""`).
{% endhint %}

#### Response

The Access Grant URL if any matches the search criteria.

#### Access Control

* The tool only searches Access Grants issued to the agent identified by the access token.

## Resource Management Tools

### `getResource`

Retrieves the content of a resource that the agent has access to, for example through an Access Grant.

#### Request Parameters

| Parameter         | Type   | Required | Description                     |
| ----------------- | ------ | -------- | ------------------------------- |
| **`resourceUrl`** | String | Yes      | URL of the resource to retrieve |

#### Response

{% hint style="warning" %}
Changed in version 3.5.0. Before version 3.5.0, `getResource` returned the resource content as plain text. It now returns an MCP [embedded resource](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#embedded-resources) that carries the content together with its URL, content type, and ETag. Clients that read the content as text must read it from the embedded resource instead.
{% endhint %}

On success, the tool result contains a single content item of type **`resource`**:

```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
}
```

| Field                     | Description                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| **`resource.uri`**        | The canonical URL of the resource. This can differ from the `resourceUrl` the client provided. |
| **`resource.mimeType`**   | The resource's content type, as returned by Pod Storage                                        |
| **`resource.text`**       | The resource content                                                                           |
| **`resource._meta.etag`** | The resource's ETag. Omitted if the resource has none.                                         |

#### Access Control

* Only URLs of resources stored in ESS are accepted.
* ESS checks that the agent identified by the access token can read the resource, in the same way as for any other request to Pod Storage. Access to another user's resource requires an active Access Grant issued to the agent; revoking the Access Grant takes effect immediately.

#### Errors

The tool returns a tool error if the resource URL is not recognized, the resource cannot be found, or the agent does not have permission to read it.

## Tool Errors

When a tool cannot complete because of its input, the caller's access, or a failure in another ESS service, it returns an MCP tool error with a short explanation, rather than a protocol error. A temporary failure of another ESS service is reported as the server being busy; retry the call later.

## Configuration

As part of the [installation process](https://docs.inrupt.com/ess/installation.md), Inrupt provides base Kustomize overlays and associated files that require deployment-specific configuration inputs.

The following configuration options are available for the MCP Service.

### Required Configuration

#### **INRUPT\_MCP\_HTTP\_BASE\_URL**

The public base URL of the MCP Service, for example `https://mcp.{ESS_DOMAIN}`.

#### **INRUPT\_MCP\_AUTHENTICATION\_AS\_URI**

The URL of the Platform Management service, which issues access tokens for the MCP Service. Only tokens from this issuer are accepted, and it is advertised in the [protected resource metadata](#protected-resource-metadata).

#### **INRUPT\_STORAGE\_HTTP\_BASE\_URL**

{% hint style="info" %}
Replaces `INRUPT_MCP_RESOURCE_STORAGE_SERVICE` in version 3.5.0.
{% endhint %}

The public base URL of the Pod Storage service. `getResource` only retrieves resources under this URL.

#### **INRUPT\_VC\_HTTP\_BASE\_URL**

{% hint style="info" %}
Replaces `INRUPT_MCP_RESOURCE_ACCESS_GRANT_SERVICE` in version 3.5.0.
{% endhint %}

The public base URL of the Access Grant Service.

## Additional Information

* [ESS Access Grant Service](https://docs.inrupt.com/ess/services/service-access-grant.md)
* [Access Tokens](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md)
* [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2026-07-28)
* [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728)
