MCP Server

Colectica Portal includes a Model Context Protocol (MCP) server. MCP is an open standard that lets AI assistants and agents call tools provided by an application. The Colectica MCP server gives assistants such as Claude, ChatGPT, or coding agents a set of read-only tools for investigating the metadata in Colectica Repository: searching for items, listing the variables and questions in a study, summarizing coverage, finding similar variables, comparing items, tracing lineage, and listing code values.

Overview

The MCP server is part of the Colectica Repository web application. No separate installation is needed.

Endpoint

https://{example.org}/mcp

Transport

Stateless Streamable HTTP. Clients send JSON-RPC requests with POST.

Tools

Twelve read-only catalog tools, described below. No prompts or resources are exposed.

Content

The tools return compact catalog metadata: identifiers, names, labels, descriptions, and links to the Portal item pages. They never return raw DDI XML, attachment contents, credentials, or observation data.

Note

The MCP server is a read-only view of the repository. All tools are marked as read-only and idempotent, and none of them modify the repository.

Enable the MCP Server

The MCP server is disabled until an administrator enables it.

1. Confirm that the MCP endpoint feature is available on the Feature Access page. The MCP endpoint is licensed separately. If the feature is not available, the MCP settings are shown but cannot be changed.

2. Navigate to Admin and choose Site Information.

3. In the API section, check Enable MCP endpoint.

4. Optionally, check Require authentication for MCP endpoint. See Authentication below.

5. Click Save.

While the endpoint is disabled, requests to /mcp return 404 Not Found.

Authentication

Access to the MCP server follows the Portal’s access rules.

Anonymous portals

If Allow anonymous access is enabled in Site Information, the MCP server can be used without credentials. The Require authentication for MCP endpoint setting has no effect on a portal that allows anonymous access.

Portals that require login

If anonymous access is not allowed and Require authentication for MCP endpoint is checked, every MCP request must be authenticated. Unauthenticated requests receive 401 Unauthorized.

Authenticated requests use a bearer token in the Authorization header. Tokens are validated using either of the REST API’s token providers:

• OpenID Connect. When an audience is configured in the OpenIDConnect:Audience setting, the token must include that audience.

• The local JWT token provider.

If neither provider is enabled, requests that carry a bearer token are rejected.

When OpenID Connect is configured, the Portal also publishes an OAuth protected resource metadata document at https://{example.org}/.well-known/oauth-protected-resource/mcp. MCP clients that support OAuth discovery use this document to find the authorization server (the OpenIDConnect:Authority) and the supported scopes (profile and email), and the 401 response includes a WWW-Authenticate: Bearer resource_metadata="..." header pointing to it.

Cross-origin requests from browsers must use a bearer token. A cross-origin request that relies on a Portal login cookie is refused with 403 Forbidden.

Note

The MCP tools do not apply per-item repository permissions. Authentication controls whether a client may use the MCP server at all; it does not change which items the tools return. The get_repository_capabilities tool reports this in its repository permissions property.

Configuration

Two server-side settings in appsettings.json control the MCP server. See appsettings.json for how to edit this file.

"Mcp": {
  "TimeoutSeconds": 30,
  "RateLimitPerMinute": 60
}

Mcp:TimeoutSeconds

The maximum time allowed for a single MCP request, from 1 to 300 seconds. Requests that exceed the limit receive 504 Gateway Timeout. The default is 30.

Mcp:RateLimitPerMinute

The number of MCP requests allowed per minute for each client, from 1 to 10000. Clients are identified by the token’s subject, the user name, or the remote IP address. Requests over the limit receive 429 Too Many Requests. The default is 60.

The cultures offered by the tools come from the SupportedLanguages setting.

Connect a Client

Point any MCP client that supports the Streamable HTTP transport at the endpoint URL. The exact steps depend on the client. A typical JSON configuration, for clients that read an mcpServers block, looks like the following.

{
  "mcpServers": {
    "colectica": {
      "type": "http",
      "url": "https://example.org/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOi..."
      }
    }
  }
}

• Replace example.org with your Portal hostname. If the Portal is hosted under a path prefix, include the prefix before /mcp.

• Omit the headers block on portals that allow anonymous access.

• A token from the local JWT token provider can be pasted directly. Clients that support OAuth discovery can obtain a token from your OpenID Connect provider automatically.

Clients that only support the stdio transport need a bridge such as mcp-remote to reach an HTTP server.

Item References

Several tools take an item reference, or a list of them. An item reference is a JSON object with the item’s identification information.

{
  "agencyId": "example.org",
  "identifier": "e9d35174-dea3-4629-afef-770220b4cbc4",
  "version": 1
}

version may be omitted, in which case the latest version of the item is used.

Every item returned by the tools is an item summary with the following properties.

agencyId, identifier, version

The identification of the item.

itemType, itemTypeName

The item type identifier and its name. See Item Type Identifiers.

name, label, summary, description, displayLabel

The main text of the item, in the preferred language.

webUrl

A link to the item’s page in Colectica Portal.

versionDate

The date and time the version was registered.

isDeprecated

Whether the item is deprecated.

tags

Any tags applied to the version.

Paged tools return an object with items, total, and nextCursor properties. To retrieve the next page, pass the nextCursor value back to the same tool in its cursor parameter. The default page size is 25 items and the maximum is 100.

Tools

get_repository_capabilities

Describes the supported item types, root types, cultures, limits, privacy boundaries, and guidance for using the catalog tools. This tool takes no parameters. Assistants should call it first to learn which item type names are accepted by the other tools.

search_items

Searches metadata text across the repository, or recursively within up to ten root sets.

query

Words to search for. Omit the query to list all items of the requested types. Up to 20 words are used.

itemTypes

Optional item type names (such as Variable or StudyUnit) or item type identifiers.

roots

Optional item references. When present, only items within the sets of these roots are searched.

cultures

Optional languages to search, such as en-US or fr.

pageSize, cursor

Paging controls.

includeDeprecated

Whether to include deprecated items. Defaults to false.

get_item

Returns the item summary for a single item.

item

The item reference.

list_variables

Lists the variables recursively contained by a dataset, data file, study, series, or other root.

root

The item reference of the set root.

query

Optional text used to search within the set.

pageSize, cursor, includeDeprecated

As for search_items.

list_questions

Lists the questions and question grids recursively contained by a questionnaire, study, series, or other root.

root

The item reference of the set root.

query

Optional text used to search within the set.

includeQuestionBlocks

Whether to also return question blocks. Defaults to false.

pageSize, cursor, includeDeprecated

As for search_items.

summarize_set

Counts the item types contained in a root’s set and identifies the principal items: series, studies, questionnaires, data files, data layouts, concepts, and universes.

root

The item reference of the set root.

The result includes totalContainedItems, countsByType, and up to 100 principalItems.

summarize_coverage

Summarizes the subjects, keywords, time periods, geography, and languages described by the items in a root’s set, along with counts of related concepts, universes, variables, questions, and the links among them.

root

The item reference of the item or set root.

find_similar_items

Finds variables, questions, or question grids that are similar to a given item. Similarity is deterministic and explainable. Each result includes a score from 0 to 100 broken down by shared represented variable, shared conceptual variable, concept overlap, universe overlap, representation overlap, source or lineage overlap, and text overlap, along with the shared references and matched terms.

item

The source variable, question, or question grid.

root

Optional item reference used to limit candidates to a set. When omitted, the whole repository is searched.

maximumResults

Defaults to 25 and is capped at 100.

compare_items

Compares between two and ten variables, or between two and ten questions, and reports their common and differing concepts, universes, represented variables, conceptual variables, sources, code lists, representations, and text terms.

items

Two to ten item references. Variables and questions cannot be mixed in one comparison.

find_related_items

Explores the incoming and outgoing relationships of an item.

item

The item reference at which exploration starts.

direction

incoming, outgoing, or both. Defaults to both.

depth

The traversal depth, from 1 to 3. Defaults to 1.

maximumResults

The maximum number of relationships to return. Defaults to 25 and is capped at 100.

The result lists each relationship with its from and to items, direction, and depth, and indicates whether the result was truncated.

trace_lineage

Explains the paths that connect questions, variables, data files, data layouts, studies, series, questionnaires, represented variables, and conceptual variables to a given item.

item

The item reference whose lineage should be traced.

maximumDepth

The maximum path length, from 1 to 5. Defaults to 3.

maximumPaths

The maximum number of paths to return. Defaults to 25 and is capped at 100.

list_code_values

Lists the codes and category labels of a code list, or of the code list used by a variable, question, or question grid. Each value includes its label, category identification, hierarchy path, and whether it represents a missing value.

item

The code list, variable, question, or question grid.

responseDomainIndex

For questions and question grids, the zero-based index of the response domain to use. Defaults to 0.

pageSize, cursor

Paging controls.

Logging

Each tool call writes an information-level log message recording the tool name, duration, result count, status (success, cancelled, or error), and whether the caller was authenticated. Query text and user names are not logged. To see these messages, set the Serilog:LogLevel setting to Information. See Observability.