MCP Service

The GetFTR MCP Service provides an MCP interface for the GetFTR Entitlements API. It is designed for AI agents and MCP-compatible clients that need to retrieve entitlement decisions for scholarly content.

What is MCP?

Model Context Protocol (MCP) is a standard way for AI applications to discover and call external tools using structured input and output.

In practice:

A client connects to an MCP endpoint
The client lists available tools
The client calls a tool with JSON arguments
The service returns a structured result or error

Why use the MCP Service?

If your application already uses AI agents, the MCP Service gives you a direct and standardized way to call GetFTR entitlement checks without building your own agent-specific wrapper around the REST API.

If you are not using agents, the regular Entitlements API integration in this documentation set is still the recommended path.

Endpoint and Authentication

The MCP Service endpoint is:


https://mcp.prod.getft.io/mcp

Health check endpoint:


https://mcp.prod.getft.io/health

Authentication uses bearer token format:


Authorization: Bearer <GETFTR_API_KEY>

⚠️

The bearer token is your GetFTR API key. Keep it server-side and never expose it in browser code.

Quick Client Configuration

Example MCP client configuration:


{
  "mcpServers": {
    "getftr": {
      "type": "streamable-http",
      "url": "https://mcp.prod.getft.io/mcp",
      "headers": {
        "Authorization": "Bearer <GETFTR_API_KEY>"
      }
    }
  }
}

Typical client call sequence:

initialize
tools/list
tools/call

Available Tools

Tool name	Status	Purpose
`get_entitlements`	Available	Get real-time entitlement results for a DOI batch
`get_centralised_entitlements`	Available	Get fast, centralised entitlement results for a DOI batch

Tool: `get_entitlements`

Returns entitlement results for one or more DOI strings and optional organisation context.

Request Schema

The tool arguments object:

Property	Type	Required	Description
`dois`	`string[]`	✅	1-20 DOI strings. Each DOI must start with `10`
`org`	`object`	❎	Optional organisation context
`org.ipv4`	`string`	❎	End-user IPv4 address
`org.entityID`	`string`	❎	Organisation SAML entityID

Example arguments:


{
  "dois": ["10.1000/xyz", "10.1038/s41586-024-12345-6"],
  "org": {
    "ipv4": "203.0.113.10",
    "entityID": "https://idp.example.edu/idp"
  }
}

ℹ️

This MCP service currently accepts DOI strings only. The wider Entitlements API supports richer DOI object requests (see the Integrators Request page), but that shape is not enabled in this MCP input schema yet.

Response Schema

The tool returns an MCP result with:

result.isError - boolean
result.structuredContent - typed entitlement payload on success
result.content - text content (stringified JSON)

structuredContent shape:

Property	Type	Description
`entitlements`	`EntitlementItem[]`	Up to 20 entitlement items

EntitlementItem fields:

Property	Type	Required	Description
`doi`	`string`	✅	DOI resolved by GetFTR
`statusCode`	`number`	✅	Entitlement status for this DOI
`uid`	`string`	❎	Optional request correlation identifier
`entitled`	`string`	❎	Entitlement decision (`yes`, `no`, etc.)
`accessType`	`string`	❎	Access type (`paid`, `open`, etc.)
`source`	`string`	❎	GetFTR entitlement source
`org`	`object`	❎	Org identifiers used by upstream checks
`vor`	`Document[]`	❎	Version of Record links
`av`	`Document[]`	❎	Alternative Version links
`document`	`string`	❎	Landing page URL
`updates`	`Update[]`	❎	Retraction and update data
`licenses`	`License[]`	❎	Document license data
`metadata`	`Metadata`	❎	Bibliographic metadata

Nested object shapes:

Document: { contentType?: string, url: string }
Update: { source: string, updateType: string, updateDoi: string, updateDate: string, reasons?: string[], urls?: string[] }
License: { type?: string, url?: string, startDate?: string }
Metadata: { title?: string, journal?: string, published?: string, authors?: string[] }

Example success result:


{
  "jsonrpc": "2.0",
  "id": "call-1",
  "result": {
    "isError": false,
    "structuredContent": {
      "entitlements": [
        {
          "doi": "10.1000/xyz",
          "statusCode": 200,
          "entitled": "yes",
          "accessType": "paid"
        }
      ]
    }
  }
}

Error Handling

Scenario	Behavior
Missing bearer token on `/mcp`	HTTP `401`
Upstream entitlement API returns `401`	`isError: true` with message `Invalid GetFTR API key provided.`
Upstream entitlement API returns `400`	`isError: true` with message `GetFTR API request was invalid.`
Other upstream non-2xx status	`isError: true` with message `GetFTR API request failed with status <code>.`

Tool: `get_centralised_entitlements`

Get fast, centralised entitlement results for a DOI batch. This tool provides DOI-level entitlements against Journal ISSN entitlements for institutional subscriptions.

Integration Notes

Keep DOI batches at 20 or fewer per call.
Prefer structuredContent for parsing logic.
Treat isError: true as a normal runtime branch and handle gracefully.
The service forwards your request to the configured GetFTR Entitlements API URL.