> 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/mcp-resource.md).

# MCP Resource Service

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

The MCP Resource Service provides Model Context Protocol (MCP) tools that enable AI agents and applications to interact with personal data in ESS, given the appropriate access by the user. It implements the MCP specification for AI-driven resource interactions with a focus on consent-based access control.

## Overview

The Resource Service exposes four MCP tools organized into two categories:

### Access Management Tools

Tools for managing Access Requests and Grants:

* **`requestAccess`**: Create new Access Requests for resources
* **`checkAccessRequestStatus`**: Monitor the status of pending Access Requests
* **`hasMatchingAccessGrant`**: Verify if valid Access Grants exist for resources

### Resource Management Tools

Tools for retrieving actual resource data:

* **`getResource`**: Retrieve resource content using Access Grants

All tools require authentication via ESS Access Tokens obtained through the [Platform Management service](/ess/services/service-platform-management/token-exchange.md).

## Base URL

By default, the MCP Resource Service runs from:

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

## 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/ess/guides/integrating-with-ess-mcp.md) guide.

## Authentication

Before using any MCP tools, clients must obtain an ESS Access Token by authenticating with an external Identity Provider and exchanging the resulting ID token through the [Platform Management service](/ess/services/service-platform-management/token-exchange.md).

The ESS Access Token identifies the authenticated user. All MCP operations are scoped to this user — the MCP service enforces that the agent can only act within the boundaries of the authenticated user's access rights.

## Access Management Tools

### `requestAccess`

Creates a new Access Request for one or more resources. 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 modes requested: only `read` is currently supported |
| **`dataSubject`** | String | Yes      | WebID of the Resource Owner                                |
| **`purpose`**     | String | Yes      | Purpose or reason for the Access Request                   |

#### Response

The created Access Request URL.

#### Access Control

**Delegator Restriction:**

* The Access Request is automatically attributed to the authenticated user.

**Purpose:** Prevents the user from spoofing the agent identity to issue Access Requests to resources of other users. The agent can only create requests that are properly attributed to the authenticated end user interacting with the agent.

### `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`
* `cancelled`

#### Access Control

**Delegator Restriction:**

* The agent can only check the status of Access Requests issued to the current authenticated user
* Attempting to check the status of Access Requests created for other users will fail with an authorization error

### `hasMatchingAccessGrant`

Verifies whether valid (active, non-revoked, non-expired) Access Grants exist for specified resources with the required access modes.

#### Request Parameters

| Parameter         | Type   | Required | Description                                                                                 |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| **`resourceUrl`** | String | Yes      | URL of the target resource to check                                                         |
| **`purposeUrl`**  | String | No       | URL of the purpose                                                                          |
| **`mode`**        | String | Yes      | Access modes to verify: only `read` is currently supported                                  |
| **`dataSubject`** | String | Yes      | WebID of the agent who should issued the Access Grant                                       |
| **`status`**      | String | No       | Access Grant status ('active', 'revoked', or 'expired'), defaults to 'active' if left blank |

#### Response

The Access Grant URL if any matches the search criteria.

#### Access Control

**Delegator Restriction:**

* The agent can only check for Access Grants where the grantee is the current authenticated user
* Attempting to check for grants issued by other users will fail with an authorization error

## Resource Management Tools

### `getResource`

Retrieves the actual content of a resource using a valid Access Grant. The client must have a valid ESS Access Token.

#### Request Parameters

| Parameter            | Type   | Required | Description                                |
| -------------------- | ------ | -------- | ------------------------------------------ |
| **`resourceUrl`**    | String | Yes      | URL of the resource to retrieve            |
| **`accessGrantUrl`** | String | Yes      | URL of the Access Grant authorizing access |

#### Response

On success, the resource content is returned.

#### Access Control

**Delegator Restriction:**

* The agent can only retrieve resources using Access Grants issued by the current authenticated user
* The service validates that the grant's `isProvidedTo` field matches the agent's identity

**Grant Validation:** The service performs comprehensive validation before retrieving the resource:

* The Access Grant must exist and not be revoked
* The Access Grant must not have expired
* The Access Grant must authorize access to the requested resource
* The Access Grant must have been issued to the agent
* The Access Grant must include the required access modes

## Configuration

As part of the [installation process](/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 Resource Service.

### Required Configuration

#### HTTP Base URL

**Environment Variable:** `INRUPT_MCP_RESOURCE_HTTP_BASE_URL`

The base URL where the Resource Service is accessible.

#### Storage Service URL

**Environment Variable:** `INRUPT_MCP_RESOURCE_STORAGE_SERVICE`

URL of the ESS Storage Service for retrieving resources.

#### Access Grant Service URL

**Environment Variable:** `INRUPT_MCP_RESOURCE_ACCESS_GRANT_SERVICE`

URL of the Access Grant Service.

## Additional Information

* [ESS Access Grant Service](/ess/services/service-access-grant.md)
* [Platform Management service](/ess/services/service-platform-management/token-exchange.md)
* [Model Context Protocol Specification](https://modelcontextprotocol.io/)