Model Context Protocol

The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Blue Morpho. This guide covers how to connect Blue Morpho to the following AI tools using MCP:

Cursor
Claude desktop

Once connected, your AI assistants can interact with and query your Blue Morpho projects on your behalf. To see a list of available tools, see here.

Step 1: Create a personal access token

First, go to your Blue Morpho settings and create an API key (personal access token). This will be used to authenticate the MCP server with your Blue Morpho account.

Step 2: Configure your AI tool

MCP-compatible tools can connect to Blue Morpho using the Blue Morpho remote MCP server.

Cursor

In Cursor settings, search for "mcp". In "Tools & Integrations", click on "New MCP Server".

This creates a mcp.json file:

{
  "mcpServers": {
    "blue-morpho": {
      "type": "url",
      "url": "https://app.getbluemorpho.com/mcp/",
      "headers": {
        "X-API-Key": "YOUR-API-KEY-HERE"
      }
    }
  }
}

Replace YOUR-API-KEY-HERE with your Blue Morpho API key (or preferably, use environment variables).

Save the file. Navigate back to Settings → MCP. You should see a green active status once connected.

Claude desktop

Navigate to Settings → Developer → Edit Config:

{
  "mcpServers": {
    "blue-morpho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.getbluemorpho.com/mcp/",
        "--header",
        "X-API-Key: YOUR-API-KEY-HERE"
      ]
    }
  }
}

Replace YOUR-API-KEY-HERE with your Blue Morpho API key (or preferably, use environment variables).

Restart Claude. Navigate back to Settings → Developer → Edit Config. You should see your running MCP connection.

Step 3: Use Blue Morpho MCP tools

Once your AI tool is connected to Blue Morpho via MCP, you can immediately begin issuing commands to interact with your projects.

Try asking your AI assistant to list Blue Morpho projects to make sure everything is working properly!

Learn more about the Blue Morpho tools accessible through MCP below.

Project and Knowledge Base Management

`list_projects`

Lists all projects in the application.

Parameters:
None

Usage:
Useful for discovering available projects to work with.

`list_knowledge_bases`

Lists all knowledge bases within a specific project.

Parameters:
- project_id

Usage:
Helps you find the knowledge bases available for analysis.

Document Management

`list_knowledge_base_documents`

Lists the original documents used to build a knowledge base.

Parameters:
- project_id
- knowledge_base_id

Usage:
Shows you what source documents were processed to create the graph.

`get_knowledge_base_document_urls`

Provides download URLs for specific documents.

Parameters:
- project_id
- knowledge_base_id
- document_id

Returns:
Pre-signed AWS S3 URLs (expire after 30 minutes).

Usage:
Essential for accessing the original document content.

Graph Structure and Ontology

`get_knowledge_base_ontology_version`

Retrieves the ontology (schema) for a knowledge base.

Parameters:
- project_id
- knowledge_base_id

Usage:
Critical: Must be called before any graph querying to understand the data structure.

Graph Querying and Search

`compute_cypher_query`

Executes Cypher queries against the graph database.

Parameters:
- cypher_query
- project_id
- knowledge_base_id

Notes:
- Uses Memgraph’s Cypher implementation (openCypher standard).
- Prerequisite: Retrieve ontology first.

`search_node_in_graph`

Searches for nodes matching a query within the graph.

Parameters:
- search_query
- project_id
- knowledge_base_id
- node_type_name (optional, searches all types if not specified)
- max_number_results (optional, max 30)

Limitations:
- Cannot search SourceDocument nodes.
- Prerequisite: Retrieve ontology first.

Key Workflow

Discovery:
List projects → List knowledge bases
Schema Understanding:
Get ontology (mandatory before querying)
Data Exploration:
Search nodes or run Cypher queries
Document Access:
List documents → Get document URLs for original sources

Important Notes

Ontology First: Always retrieve and display the ontology before performing any graph operations.
Time Limits: Document URLs expire after 30 minutes.
Query Limits: Node searches return a maximum of 30 results.
Cypher Compatibility: Uses openCypher standard (no APOC or Neo4j-specific functions).
Source Documents: Use the document URL tool instead of querying SourceDocument nodes directly.