.. _mcp:
Dimensions Analytics MCP
========================
The `Dimensions Analytics MCP `_ server connects AI assistants — such as `Claude Desktop `_, `Cursor `_, GitHub Copilot in VS Code, and Windsurf — to Dimensions research data through the `Model Context Protocol (MCP) `_.
Once configured, you can ask your assistant — in plain language — to:
* Search publications, grants, researchers, and other record types
* Run analytics, facets, and trend queries
* Look up records by DOI or Dimensions ID
* Explore the live Dimensions schema
For example: *"Find the 20 most-cited publications on CRISPR gene editing since 2020."*
You can run the server in two ways:
* **Local** — the server runs on your computer: the :ref:`Claude Desktop extension `, the :ref:`guided installer `, or :ref:`manual setup `. Works with every MCP client and every Dimensions instance.
* **Hosted** — connect your app to ``https://app.dimensions.ai/mcp`` with your API key. Nothing to install or update. See :ref:`Hosted server `.
.. note::
**Subscription required**
The Dimensions Analytics API is subscription-only, so your Dimensions account must be activated for this service. MCP access is available to API subscribers, subject to the same :ref:`reasonable use ` terms. Email `supportapi@dimensions.ai `_ with any questions.
Prerequisites
-------------
Before you start, make sure you have:
* **Node.js 20 or later** — required for the guided installer and the local server. Claude Desktop provides its own Node runtime for the desktop extension, and the :ref:`hosted server ` needs none.
Check your version with ``node --version``. If it's missing or older than 20, install it from `nodejs.org `_ (the guided installer can also help you do this).
* **A Dimensions API key** — the same key used for the :ref:`Dimensions DSL API `.
Find or generate your key in Dimensions. See :ref:`Getting an API Key ` for instructions.
* **An MCP-compatible client** — for example Claude Desktop, Cursor, GitHub Copilot in VS Code, or Windsurf. Any client that supports the Model Context Protocol will work; the guided installer can auto-configure the four listed here, and you can set up others manually.
Don't have an API key yet? `Request a demo or quote here `_.
.. note::
**Keep your API key private**
Treat your API key like a password. Manual MCP config files store it in plain text and are **not** encrypted — never commit them to a public repository or share them. Claude Desktop handles the extension's sensitive API-key setting.
.. _mcp-claude-desktop:
Install in Claude Desktop
-------------------------
1. `Download the latest Dimensions Analytics extension `_.
2. In Claude Desktop, open **Settings → Extensions → Advanced settings → Install Extension…** and select the downloaded ``.mcpb`` file.
3. Enter your Dimensions Analytics API key. If your account uses a custom Dimensions instance, also set its URL. Then ask: *"Find the 20 most-cited publications on CRISPR gene editing since 2020."*
The extension bundles the local server and its dependencies. Claude Desktop supplies Node.js and handles the API-key setting as sensitive configuration. Your account needs Analytics API access.
To update a bundle installed from GitHub, download and install the latest ``.mcpb`` again. Sideloaded bundles do not update automatically; extensions installed from Claude's directory do. For Cursor, VS Code, Windsurf, and other MCP clients, use the :ref:`guided installer ` or :ref:`manual setup `.
.. _mcp-quick-install:
Quick install
-------------
The guided installer checks Node.js, downloads the server from npm, asks for your API key, and configures your chosen apps — **Claude Desktop**, **Cursor**, **GitHub Copilot in VS Code**, or **Windsurf**. It installs to ``~/.dimensions-analytics-mcp``, backs up any existing config before changing it, and needs no repository clone or GitHub token.
For Cursor, VS Code, and Windsurf it also offers the :ref:`hosted server ` instead of the local one. If you choose it, the installer checks your API key and installs nothing locally for those apps.
**Mac / Linux** — paste in Terminal:
.. code-block:: shell
bash -c "$(curl -fsSL https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.sh)"
.. note::
**Copy the command exactly as shown.**
Don't rewrite it as ``curl … | bash`` — the installer won't be able to ask you questions that way.
**Windows** — paste in PowerShell:
.. code-block:: powershell
irm https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.ps1 | iex
When it finishes, **quit and reopen** each configured app.
Using a different MCP client, or want advanced options? Any MCP-compatible client works — see :ref:`Manual setup ` below to configure one yourself, or the `MCP installation guide `_ for non-interactive install and developer options.
.. _mcp-verify-installation:
Verify the installation
~~~~~~~~~~~~~~~~~~~~~~~
After restarting your app, look for **dimensions** in its MCP or connectors settings — it should show as connected. Then test it with a prompt:
*"List the available Dimensions tools."*
If the assistant responds with Dimensions tools (such as ``search_publications`` or ``describe_schema``), you're ready to go. If not, see :ref:`Troubleshooting `.
.. _mcp-manual-setup:
Manual setup
------------
If you prefer to configure the server yourself, add an entry to your MCP client's config file. This example uses ``npx``, so no global install is required:
.. code-block:: json
{
"mcpServers": {
"dimensions": {
"command": "npx",
"args": ["-y", "@digital-science-dsl/dimensions-analytics-mcp@latest"],
"env": {
"DIMENSIONS_API_KEY": "your-api-key"
}
}
}
}
.. note::
**GitHub Copilot in VS Code** uses the key ``servers`` instead of ``mcpServers``. Otherwise the structure is the same.
.. _mcp-config-file-locations:
Config file locations
~~~~~~~~~~~~~~~~~~~~~
The table below covers common clients. For any other MCP-compatible client, add the same ``dimensions`` entry to that client's MCP config file — check its documentation for the exact location and whether it uses the ``mcpServers`` or ``servers`` key.
.. list-table::
:header-rows: 1
* - Client
- Config file
* - Cursor
- ``~/.cursor/mcp.json`` or ``.cursor/mcp.json``
* - Claude Desktop (macOS)
- ``~/Library/Application Support/Claude/claude_desktop_config.json``
* - Claude Desktop (Windows)
- ``%APPDATA%\\Claude\\claude_desktop_config.json``
* - GitHub Copilot in VS Code
- User ``mcp.json`` — run **MCP: Open User Configuration** from the Command Palette (macOS: ``~/Library/Application Support/Code/User/mcp.json``). A workspace can also use ``.vscode/mcp.json``.
* - Windsurf
- ``~/.codeium/windsurf/mcp_config.json``
After editing the config, **quit and reopen** the app, then follow :ref:`Verify the installation ` above.
.. _mcp-hosted:
Hosted server
-------------
The hosted server runs the same tools without anything installed on your computer.
.. list-table::
:widths: 25 75
* - URL
- ``https://app.dimensions.ai/mcp`` (Streamable HTTP)
* - Authentication
- ``Authorization: Bearer `` — the same key as the :ref:`DSL API `
* - Instances
- Standard instance (``app.dimensions.ai``) only. If you use a custom Dimensions instance, use the local server.
* - Differences
- No Node.js and no updates on your side. ``fetch_search_pages``, which exports results to local files, is not available; every other tool is.
The :ref:`guided installer ` can set this up for Cursor, VS Code, and Windsurf. To configure it yourself:
**Cursor** (``~/.cursor/mcp.json``):
.. code-block:: json
{
"mcpServers": {
"dimensions": {
"url": "https://app.dimensions.ai/mcp",
"headers": {
"Authorization": "Bearer your-api-key"
}
}
}
}
**VS Code** (user ``mcp.json``). This version asks for your key once and keeps it out of the file:
.. code-block:: json
{
"inputs": [
{
"type": "promptString",
"id": "dimensions-api-key",
"description": "Dimensions API key",
"password": true
}
],
"servers": {
"dimensions": {
"type": "http",
"url": "https://app.dimensions.ai/mcp",
"headers": {
"Authorization": "Bearer ${input:dimensions-api-key}"
}
}
}
}
**Windsurf** (``~/.codeium/windsurf/mcp_config.json``):
.. code-block:: json
{
"mcpServers": {
"dimensions": {
"serverUrl": "https://app.dimensions.ai/mcp",
"headers": {
"Authorization": "Bearer your-api-key"
}
}
}
}
**Claude Code**:
.. code-block:: shell
claude mcp add --transport http dimensions https://app.dimensions.ai/mcp --header "Authorization: Bearer your-api-key"
**Codex CLI** (reads the key from the ``DIMENSIONS_API_KEY`` environment variable):
.. code-block:: shell
codex mcp add dimensions --url https://app.dimensions.ai/mcp --bearer-token-env-var DIMENSIONS_API_KEY
For any other client, use the URL above with an ``Authorization: Bearer`` header, then follow :ref:`Verify the installation `.
.. note::
**Apps that can't use the hosted server yet**
The hosted server authenticates with your API key, so apps that only support OAuth sign-in for remote servers can't connect to it:
* **ChatGPT** — custom MCP servers support OAuth or no authentication only.
* **claude.ai custom connectors** — not supported yet. To use Dimensions with Claude, install the :ref:`Claude Desktop extension ` in the Claude Desktop app.
**Claude Desktop** is supported: connect it with the :ref:`Claude Desktop extension `, which runs the server locally with your API key.
Using Dimensions in chat
------------------------
Once the server is connected, just ask your assistant in plain language. Example prompts:
* *"Find the 20 most-cited publications on CRISPR gene editing since 2020."*
* *"Search NIH grants about cancer immunotherapy started after 2020."*
* *"Who are the top researchers working on quantum computing?"*
* *"Look up DOI 10.1038/nature12373 and show title, citations, and journal."*
* *"Citation trend for large language model publications from 2018 to 2024."*
A few tips for better results:
* **Be specific about scope** — a year range, number of results, or source ("since 2020," "top 20," "NIH grants") gets you a sharper answer.
* **Refine with follow-ups** — the assistant keeps context, so you can narrow or expand a result instead of rewriting your question from scratch.
* **Write DSL directly if you prefer** — for advanced boolean queries or NLP functions, you can ask in `DSL `_ and the assistant will run it.
A full tool reference, example arguments, and routing notes are in the `MCP usage guide `_.
.. note::
**Rate limits**
Usage is subject to rate limits. If queries start failing or getting throttled, you may be sending requests too quickly — see the :ref:`reasonable use ` guidelines for the current limits.
.. _mcp-troubleshooting:
Troubleshooting
---------------
.. list-table::
:header-rows: 1
:widths: 25 30 45
* - Symptom
- Likely cause
- What to do
* - **dimensions** doesn't appear in your app after restarting
- Config file in the wrong location, or invalid JSON
- Confirm the path against the :ref:`config file locations ` table, and validate the JSON (a trailing comma or missing brace will silently break it).
* - Your app has no MCP / connectors settings at all
- Client version is too old to support MCP
- Update the app to the latest version, then restart it.
* - ``node: command not found`` or a Node version error
- Node.js not installed, too old, or not on your PATH
- Run ``node --version``. If it's missing or below 20, install from `nodejs.org `_, then restart your terminal and app.
* - Authentication error / ``403`` / "unauthorized"
- API key is wrong, or your account isn't activated for the Analytics API
- Re-check the key in your config (no extra spaces or quotes). Verify in Dimensions that your account has API access. If it should and doesn't work, email `supportapi@dimensions.ai `_.
* - Server is listed but tools don't respond
- Stale ``npx`` cache, or first-run download still in progress
- Wait a few seconds and retry. If it persists, run ``npx clear-npx-cache`` (or ``npm cache clean --force``) and restart the app.
* - Queries fail intermittently with rate-limit errors
- You're sending requests too quickly
- Slow down or batch requests. See the :ref:`reasonable use ` guidelines.
* - Hosted server: ``fetch_search_pages`` is missing
- Exports to local files need the local server
- Expected. Use the local server if you need exports; every other tool works on the hosted server.
* - Hosted server rejects a key from a custom instance
- The hosted endpoint serves the standard instance only
- Use the local server with your instance URL (the guided installer asks for it).
* - Installer can't read your input
- The install command was piped to ``bash``
- Use the ``bash -c "$(curl …)"`` form shown in :ref:`Quick install `, not ``curl … | bash``.
Still stuck? Email `supportapi@dimensions.ai `_ with your client name and version, your OS, the output of ``node --version``, and the error message you're seeing.
Updating and uninstalling
-------------------------
**Updating**
* **Installed via the guided installer:** the server checks npm about once a day and installs new minor and patch releases automatically. Major versions are never applied automatically — re-run the install command to upgrade.
* **Hosted server:** nothing to update.
* **Configured manually with ``npx``:** include ``@latest`` in the package argument to request the current release. Without it, ``npx`` may reuse its cached version. Restart your app after updating.
**Uninstalling**
1. Remove the ``dimensions`` entry from each app's config file (see :ref:`config file locations `). For the hosted server, that is all you need to do.
2. If you used the guided installer, also delete its install directory: ``~/.dimensions-analytics-mcp``.
3. Restart each app.
Further documentation
---------------------
The MCP server repository includes full reference documentation:
* `Installation `_ — guided installer, manual setup, the hosted server, non-interactive install, and build from source.
* `Usage guide `_ — workflows, the full tool reference, and example prompts. *Start here if you want to get the most out of the available tools.*
* `Reference `_ — environment variables, rate limits, and schema cache behaviour.
* `Field aliases `_ — field-name shortcuts accepted by the search tools.
Package: `@digital-science-dsl/dimensions-analytics-mcp `_ on npm.