MCP Resource Service
Added in version 3.0.0
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 resourcescheckAccessRequestStatus: Monitor the status of pending Access RequestshasMatchingAccessGrant: 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.
Base URL
By default, the MCP Resource Service runs from:
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 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.
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
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
accessRequestUrl
String
Yes
URL of the Access Request to check
Response
The Access Request status, i.e. one of:
pendinggranteddeniedcancelled
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
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
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
isProvidedTofield 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, 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
Last updated