Overview

The Dimensions Semantic Search MCP server provides powerful semantic access to annotated scientific document repositories — including publications, grants, patents, and clinical trials — directly within your AI environment. Documents are enriched with ontological concept annotations covering 40+ life science domains, enabling concept-aware search that automatically includes all subtypes via the ontological is-a hierarchy (e.g. querying “cancer“ finds every cancer subtype indexed in the corpus). For a detailed breakdown of the underlying data structures and rate limits, please refer to the API Documentation.

What is Dimensions?

Dimensions is a comprehensive research database that indexes millions of scholarly publications, grants, patents, and clinical trials. The Dimensions Semantic Search MCP draws on this broad index, allowing you to:

• Search publications, patents, and clinical documents with semantic precision
• Resolve scientific terms to ontological concepts across 40+ life science domains
• Discover co-occurring concepts across the literature

Use Cases

Technical

• Deep literature reviews combining lexical and concept-based search in full-text
• Co-occurrence and relationship mining across whole repositories, e.g. drug–disease in publications or patents
• Ontological exploration: finding all subtypes of a disease or compound class
• Chemistry search linked to document retrieval

Application oriented

• Clinical evidence discovery for a compound or indication
• Trend Monitoring for e.g. indications and their treatments. Track the latest drug publications in oncology (e.g., Breast Cancer treatments over 6 months)
• Market Intelligence in e.g. drug discovery. For example to differentiate clinical and pre-clinical candidates in one query
• Safety & Toxicology insights, e.g. find sentence-level correlations between compounds (PFAS) and toxicology (neurotoxicity)
• Bio-Network Mapping, e.g. map connections between tyrosine kinase inhibitors, proteins, genes, cell lines, and physiological processes

Installation

Requirements

• An MCP-compatible client. Claude Desktop users can install a ready-made extension (Option A). All other clients — Cursor, VS Code, Goose, OpenAI Codex — are configured manually (Option B).
• Membership of an organisation with access to Dimensions Semantic Search. No API key is needed to sign in; if you want one for manual configuration, obtain it from the Digital Science Platform Portal.

Authentication

Browser sign-in (OAuth) works for any user in an organisation with access to Dimensions Semantic Search. Nothing is stored in your configuration: on first connect a browser window opens for you to sign in, and the resulting token is cached locally so later launches are silent. This is the recommended method, and the only one needed for Claude Desktop.

API keys remain available and are the better choice where an interactive browser sign-in is impractical — shared machines, containers, CI, or automated workflows — and in clients that support the native HTTP transport. Obtain a key from the Digital Science Platform Portal.

Option A — Claude Desktop extension

For Claude Desktop, we publish the server as a .mcpb extension bundle. Installing it requires no configuration file, no command line, no Node.js installation and no API key — the bridge to our API is included inside the bundle, and there are no settings to fill in.

Dimensions Semantic Search MCP (OAuth) — version 1.3.7, 1.6 MB

Installing

1. Download the bundle.
2. Double-click the downloaded .mcpb file. Claude Desktop opens and shows the extension, its publisher, and the tools it provides. Alternatively: Settings → Extensions → Advanced settings → Install extension.
3. Confirm the install.
4. Start a new chat and ask “Search Dimensions for recent publications on [topic]“ to confirm the connection. A browser window opens once for you to sign in; after that, launches are silent.

What the bundle contains

The bundle is published by Digital Science & Research Solutions Ltd. It contains a small launcher that connects Claude Desktop to the hosted MCP server at https://api.digital-science.com/dim-semantic-search/v1/mcp, together with a bundled copy of the open-source mcp-remote bridge. No credentials are stored in the bundle and no document data is stored locally. Requires Claude Desktop 0.10.0 or later on macOS, Windows, or Linux.

Option B — Manual configuration

Use this for Cursor, VS Code, Goose, OpenAI Codex, and other MCP clients — or for Claude Desktop if you prefer to manage the configuration file yourself.

Each client below is shown with both methods. Browser sign-in runs through the mcp-remote bridge, launched as a command; because it is just a command, the block is identical in every client and only the outer wrapper key changes (VS Code nests servers under mcp.servers). API key setups use the native HTTP transport (type: "http") where supported, and mcp-remote with a --header X-API-KEY argument in command-only clients.

Install in Cursor

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Add one of the following to your Cursor ~/.cursor/mcp.json file.

With OAuth (browser sign-in):

{
  "mcpServers": {
    "dim-semantic-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.digital-science.com/dim-semantic-search/v1/mcp",
        "33418",
        "--disable-resource-parameter",
        "--static-oauth-client-info",
        "{\"client_id\":\"35sbbura2k8kairdas6pabofbe\"}"
      ]
    }
  }
}

With an API key:

{
  "mcpServers": {
    "dim-semantic-search": {
      "url": "https://api.digital-science.com/dim-semantic-search/v1/mcp",
      "headers": {
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Install in VS Code

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

With OAuth (browser sign-in):

"servers": {
  "dim-semantic-search": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://api.digital-science.com/dim-semantic-search/v1/mcp",
      "33418",
      "--disable-resource-parameter",
      "--static-oauth-client-info",
      "{\"client_id\":\"35sbbura2k8kairdas6pabofbe\"}"
    ]
  }
}

With an API key:

"servers": {
  "dim-semantic-search": {
    "type": "http",
    "url": "https://api.digital-science.com/dim-semantic-search/v1/mcp",
    "headers": {
      "X-API-KEY": "YOUR_API_KEY"
    }
  }
}

Install in Claude Desktop (manual)

Add one of the following to your claude_desktop_config.json.

With OAuth (browser sign-in):

{
  "mcpServers": {
    "dim-semantic-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.digital-science.com/dim-semantic-search/v1/mcp",
        "33418",
        "--disable-resource-parameter",
        "--static-oauth-client-info",
        "{\"client_id\":\"35sbbura2k8kairdas6pabofbe\"}"
      ]
    }
  }
}

With an API key:

{
  "mcpServers": {
    "dim-semantic-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.digital-science.com/dim-semantic-search/v1/mcp",
        "--header",
        "X-API-KEY: YOUR_API_KEY"
      ]
    }
  }
}

Troubleshooting

list_repositories comes back empty. This is not an authentication failure — the server returns an empty catalogue when it cannot reach its search backends. Retry, and contact support if it persists.

Browser sign-in does not complete. Sign-in needs local port 33418 free while it runs. If a sign-in tab has been left open and abandoned, close it and restart your client.

“The endpoint rejected the configured API key (HTTP 401)“. Manual API-key setups only. The key is wrong, expired, or not entitled to this service — check it in the Developer Portal.

The extension shows an error and no tools appear. Claude Desktop does not display extension error output, so the bundle writes its own log:

• macOS: ~/Library/Logs/dim-semantic-search-mcpb-oauth.log
• Windows / Linux: dim-semantic-search-mcpb-oauth.log in the system temp directory

Attach that log when contacting support@dimensions.ai.

Available Tools

The Dimensions Semantic Search MCP exposes the following tools. They are designed to be called in a natural sequence: discover repositories and domains, resolve terms to concept IDs, then search and retrieve documents.

list_repositories

Lists all available document repositories together with the features they support. Use this to learn which sources are available (e.g. patents, clinical trials) and their technical repository names required for other tools.

list_concept_domains

Lists all available ontological concept domain prefixes (e.g. chem, diseases, drugs, proteins, species, humangenes, anatomy, methods, effects, toxicity, nutrition, companies, countries, and 30+ more). Returns the root concept of each domain's is-a hierarchy. Call this before building a query to confirm which domains are available.

document_schema

Returns the document schema for a repository, including:

• Available term locations (e.g. title, ta = title+abstract, claims, description) for restricting search to document sections
• Extra fields queryable via the x_ prefix
• Facet categories for concept aggregation
• Sort criteria and available metadata attributes

Parameters:

• repository (required): Repository name from list_repositories

suggest_terms

Autocomplete-style term lookup returning matching concept OCIDs across all domains. Use this when you have a partial or uncertain term and want to discover matching concepts and their domains.

Key behaviour: the same term can match concepts in multiple domains with different meanings. Always select OCIDs from domains matching the user's semantic intent and OR-group OCIDs from related domains (e.g. chem + polymers for a chemical compound).

Parameters:

• term (required): Partial or complete term string

get_term_concepts

Exact-term lookup returning every concept in every domain registered with the given term string. Faster than suggest_terms when the exact term is already known.

Parameters:

• term (required): Complete term string (e.g. "aspirin", "breast cancer")

get_concept_data

Returns concept details for a given OCID: preferred name, synonyms, domain, and relationships within the ontology hierarchy.

Parameters:

• ocid (required): Numeric concept OCID (64-bit integer)

search_documents

The primary search tool. Searches documents in a repository using a structured query string with concept-based and full-text operators. Returns ranked hits with metadata, title, and abstract.

Parameters:

• repository (required): Repository name
• query (required): Query string (see Query Syntax below)
• hitCount (optional): Number of results to return (0 = count only; 1 = facets only)
• hitStartPos (optional): Starting position for pagination
• sortBy (optional): Sorting strategy; overrides default if included in the query string
• withDocMetaData (optional): Include document metadata (default: true)
• includeDocMetaDataAttributes (optional): Restrict returned metadata attributes

Query Syntax overview:

Occurrence operators: + = MUST, - = MUST NOT, omitted = SHOULD. Group terms with ().

search_query_guidance

Returns detailed guidance for the search_documents tool covering proximity search, concept search modes, sorting and relevance optimisation, handling large result sets, and query examples. The AI assistant calls this automatically before building complex queries.

get_document_data

Retrieves the full document content and structure for a specific document identified by its ocDocId (obtained from search_documents results). Returns complete text, structural outline, and metadata.

Parameters:

• repository (required): Repository name
• ocDocId (required): Numeric document ID from search results

run_cooccurrence_query

Queries the pre-computed sentence-level co-occurrence index to discover which concepts co-occur with a query concept and how frequently — without returning individual documents.

Parameters:

• partner1_domain (required): Concept domain for the first partner (e.g. "diseases")
• partner1_query_term (required): Term or "*" for the whole domain
• partner1_ocids (optional): Direct list of concept OCIDs for the first partner. Takes precedence over partner1_query_term if both are provided.
• partner2_domain (optional): Second partner domain for targeted co-occurrence
• partner2_query_term (optional): Second partner term
• partner2_ocids (optional): Direct list of concept OCIDs for the second partner.
• maxTopTerms (optional): Top co-occurring concepts to return (default: 20)
• maxDirectCoocEntities (optional): Top raw concept pairs to return
• withCoocCountMatrix (optional): Return N×M co-occurrence count matrix
• maxExampleSentences (optional): Example sentences demonstrating co-occurrence
• searchMode (optional): "ONTOLOGICAL" (default, includes subtypes) or "SYNONYM" (exact concept only)

Usage Examples

Once configured, you can ask your AI assistant questions like:

Search Dimensions Publications for recent papers about PFAS compounds and hepatotoxicity

The assistant will call suggest_terms to resolve “PFAS“ and “hepatotoxicity“ to concept OCIDs across relevant domains, then build an ontological query that automatically covers all PFAS subtypes (PFOS, PFOA, PFHxS, …) and all Search Dimensions Publications for recent papers about PFAS compounds and hepatotoxicity subtypes.

Find patents mentioning aspirin and headache within 30 words of each other. Sort by relevance.

The assistant constructs a proximity query with a sort-by statement:

+(nearby:"30" +chem:"aspirin" +diseases:"headache") sortBy:"relevance"

Which drugs most frequently co-occur with Alzheimer's disease?

The assistant calls run_cooccurrence_query with partner1_domain: "diseases", partner1_query_term: "Alzheimer's disease" (or partner1_ocids: [208000024827] if term was looked up before by the LLM for its concept OCID), partner2_domain: "drugs" to retrieve the top co-occurring drug concepts by frequency.

How many papers mention both CRISPR and sickle cell disease published after 2018?

The assistant looks up the concepts for CRISPR and sickle cell disease (found in multiple domains) and builds a query with a date filter:

+(ocid:"238000010354" ocid:"108091033409") +(ocid:"208000007056" ocid:"220000000768" ocid:"220001022684" ocid:"220002026178") pdate:"2019 TO 2026"

and sets hitCount: 0 to return the count only.

Find patents of assignee OntoChem where the title mentions the exact text "pharmaceutical composition" and a mineralocorticoid receptor antagonist.

The assistant builds a query combining lexical and concept search restricted to the document title and restricting it to the specified assignee:

termloc:"title" +tr:"pharmaceutical composition" +(ocid:"229940122522" ocid:"229970000033") +(x_assignees:"281000000506" x_assignees:"280000537546")

For which clinical phase and corresponding disease is rituximab investigated in running clinical trials?

The assistant first retrieves concept for rituximab, queries document schema of clinical trials repository to get status and clinicalphase fields/facets, determines status values for running clinical trials and builds the respective query.

+(ocid:"229960004641" ocid:"229970009066" ocid:"103000000958") +(x_status:"Recruiting" x_status:"Active, not recruiting" x_status:"active" x_status:"Open to recruitment" x_status:"Enrolling by invitation") facet:"clinicalphase,DOMAIN__diseases,DOMAIN__dismesh"^20

Or simply do some discovery of the resources behind the MCP:

Which repositories are available?

Describe the dspub repository.

Describe the dspub repository schema.

Which annotation domains are available?

Which synonyms are known for aspirin?

Note: it is up to the LLM utilized by the client connecting to this MCP (your AI assistant) how it translates the user requests into calls of the MCP tools. Thus another LLM may produce a different result. The examples described above were executed by Claude Code with model Claude Sonnet 4.6.

Reasonable Use

The purpose of the API is to help authorized users surface the most relevant Dimensions research data within their internal workflows on a near real-time basis.

The API is not intended for analytical use cases or training purposes, nor to create local copies of the Dimensions data for use as an alternative to the API, which should remain as the primary source of the data. You should limit your use to what is necessary for the search task(s) you are performing, not to support non-specific tasks or to collect or benchmark Dimensions data, and never in a way which may have an adverse impact on the performance or others’ use of the API.

If you require access to substantial volumes of Dimensions data or use of data for analytical or training purposes, please let us know so that we can advise on the most appropriate means of getting that access.

If access is authorized via MCP, this is allowed at our discretion for convenience only, use restrictions and limitations must still be fully respected (never by-passed or circumvented), and you must not make use of the API in a manner that (in our absolute discretion) exceeds reasonable usage patterns. Without limiting that discretion, we may determine unreasonable usage by comparing your activity for any given period against the average of other users not making use of an MCP.

Your subscription to use the API may include a defined number of tokens. Any tokens generated in excess of that number may be revoked without notice, or subject to additional charges.

We reserve the right to impose such limits on the API as we consider are reasonable. Any account associated with a violation of these rules may be subject to enforcement action, including suspension. Please also make sure you comply with the other terms of your Dimensions subscription.