Ultipa MCP

Overview

Ultipa MCP is a Model Context Protocol server that exposes Ultipa Cloud and self-managed GQLDB instances as tools for MCP-compatible AI clients (Claude, Cursor, Windsurf, VS Code, Cline, etc.). It lets the agent provision and operate instances, run GQL queries, manage backups, view metrics, and more — all through natural language.

Ultipa MCP runs in two shapes:

• as a stdio subprocess launched by clients like Claude Desktop, Claude Code, and Cursor;
• or as a remote HTTP server at mcp.ultipa.com that Claude Web (claude.ai) connects to via OAuth.

Install

How you add Ultipa MCP depends on your client:

• Claude Desktop → Connectors directory (easiest), or manual config
• Claude Code → claude mcp add
• Claude Web (claude.ai) → remote connector (no install, OAuth-based, Ultipa Cloud only)
• Cursor, Windsurf, VS Code, other stdio clients → manual config

Stdio installs need one Ultipa target, either an Ultipa Cloud API key or a Direct instance (host + username + password). See Auth. The Claude Web connector uses OAuth and needs no env config.

Claude Desktop

The simplest path is the Connectors directory:

1. Open Claude Desktop → New Chat → + icon → Connectors → Add connector → Browse connectors.
2. Search for Ultipa and click Install. Then click Config.
3. When prompted, enter either your Ultipa Cloud API key or the direct-instance host + username + password, then Save.

If Ultipa isn't visible in your Connectors directory (older Claude Desktop, enterprise-managed install), you can install the .mcpb extension file directly:

1. Download gqldb-mcp.mcpb from Download Center.
2. Open it, or drag it into Settings → Extensions in Claude Desktop.
3. When prompted, enter your credentials (same as above).

NOTE

Team / Enterprise admins can upload the .mcpb in organization settings to make it a one-click install for the whole org.

Claude Code

Add the server with claude mcp add (it runs the published npm package via npx):

Bash
# Ultipa Cloud (API key) — --scope user makes it available in every project
claude mcp add ultipa-cloud --scope user \
  --env ULTIPA_CLOUD_API_KEY=uc_... \
  -- npx -y @ultipa-graph/gqldb-mcp

# Self-managed / direct instance
claude mcp add ultipa --scope user \
  --env ULTIPA_HOST=<host>:<port> \
  --env ULTIPA_USERNAME=<username> \
  --env ULTIPA_PASSWORD=<password> \
  --env ULTIPA_GRAPH=<optional_default_graph_name> \
  -- npx -y @ultipa-graph/gqldb-mcp

Verify with claude mcp list.

Claude Web

Claude Web supports Ultipa as a remote MCP server. Each user authenticates via OAuth against their own Ultipa Cloud account, so there's no API key to manage and every user only sees their own instances.

1. Open Claude Web → Settings → Connectors → Add custom connector.
2. Fill in:
   • Name: Ultipa (or any label you prefer)
   • Remote MCP server URL: https://mcp.ultipa.com
   • OAuth Client ID: oac_b67435362986
   • OAuth Client Secret: leave blank
3. Click Add to close the modal, then click Connect. You'll be redirected to account.ultipa.com to sign in (or create an account) and approve access.
4. Once authorized, Claude can use any of the Ultipa Cloud tools as your account.

To review or revoke access at any time, visit account.ultipa.com/connected-apps.

NOTE

Self-managed (Direct) instances aren't reachable via Claude Web. There's no per-user way to inject ULTIPA_HOST/USERNAME/PASSWORD over OAuth. For Direct instances, use Claude Desktop, Claude Code, or another stdio client.

Manual Config

Add an entry under mcpServers in your MCP client's config. The same JSON shape works in any stdio MCP client; only the file path differs:

• Claude Desktop: claude_desktop_config.json via Settings → Developer → Edit Config
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• VS Code MCP extensions: see the extension's docs.

With an Ultipa Cloud API key:

JSON
{
  "mcpServers": {
    "ultipa-cloud": {
      "command": "npx",
      "args": ["-y", "@ultipa-graph/gqldb-mcp"],
      "env": {
        "ULTIPA_CLOUD_API_KEY": "uc_..."
      }
    }
  }
}

For a direct instance:

JSON
{
  "mcpServers": {
    "ultipa-direct": {
      "command": "npx",
      "args": ["-y", "@ultipa-graph/gqldb-mcp"],
      "env": {
        "ULTIPA_HOST": "<host>:<port>",
        "ULTIPA_USERNAME": "<username>",
        "ULTIPA_PASSWORD": "<password>",
        "ULTIPA_GRAPH": "<optional_default_graph_name>"
      }
    }
  }
}

Restart your client after editing.

Multiple Targets

Each MCP server entry points at one Ultipa target. Add as many entries as you need, with descriptive names. The agent sees each entry as its own toolset and picks based on what you ask (e.g. "query staging" routes to the ultipa-staging entry).

JSON
{
  "mcpServers": {
    "ultipa-cloud": {
      "command": "npx",
      "args": ["-y", "@ultipa-graph/gqldb-mcp"],
      "env": {
        "ULTIPA_CLOUD_API_KEY": "uc_..."
      }
    },
    "ultipa-staging": {
      "command": "npx",
      "args": ["-y", "@ultipa-graph/gqldb-mcp"],
      "env": {
        "ULTIPA_HOST": "staging.internal:60061",
        "ULTIPA_USERNAME": "admin",
        "ULTIPA_PASSWORD": "..."
      }
    },
    "ultipa-prod": {
      "command": "npx",
      "args": ["-y", "@ultipa-graph/gqldb-mcp"],
      "env": {
        "ULTIPA_HOST": "prod.internal:60061",
        "ULTIPA_USERNAME": "admin",
        "ULTIPA_PASSWORD": "..."
      }
    }
  }
}

Auth

Claude Web uses OAuth — you sign into Ultipa during the connector setup. No env config needed. See Claude Web.

Stdio clients (Claude Desktop, Claude Code, Cursor, etc.) authenticate via env vars. Pick one path per server entry:

To target both, or multiple direct instances, add more entries, see Multiple Targets.

Cloud API key scopes to grant when creating the key:

Examples

Once the server is connected, talk to the agent in natural language, it picks the right tool (and target entry, if you have multiple) from the request. Examples:

Provisioning and lifecycle:

• "Spin up a new free-trial instance in Virginia, smallest size, name it sandbox."
• "What sizes are available in Frankfurt and how much do they cost per hour?"
• "Pause every instance whose name starts with dev-."
• "Upgrade sandbox to the latest GQLDB version."
• "Delete the instance old-demo."

Operations and observability:

• "Show CPU and memory for prod-cluster over the last 6 hours."
• "Tail the last 200 lines of logs from prod-cluster and tell me if anything looks wrong."
• "Set prod-cluster to debug log level for now."
• "What's my public IP, and add it to the firewall on staging?"

Backups:

• "Create an on-demand backup of prod-cluster and wait for it to finish."
• "Schedule daily backups for prod-cluster at 02:00 UTC daily."
• "Restore staging from the most recent backup of prod-cluster."

Data plane (GQL, schema, import):

• "Connect to ultipa-staging and list all graphs."
• "On the social graph, describe the schema and tell me which node types are missing indexes."
• "Run MATCH (u:User)-[:FOLLOWS]->(v:User) RETURN count(*) on the social graph."
• "Explain this query before running it: MATCH (n:User {city: 'Tokyo'}) RETURN n LIMIT 100."
• "Import the nodes in /Users/me/data/users.csv into the social graph as User nodes."
• "Run PageRank on the social graph over the FOLLOWS edges and return the top 20."
• "Who are the most influential users in the graph? List top 10."

Account and billing:

• "What's my current Ultipa Cloud balance and this month's usage?"
• "Show my balance transactions from the last 30 days."

Docs:

• "Look up the Ultipa docs on graph algorithms and summarize what's available for community detection."

Tools

Control Plane

Auth required: Ultipa Cloud — either ULTIPA_CLOUD_API_KEY (stdio clients) or a Claude Web OAuth session. Direct instances cannot use these tools.

Account

Instance Lifecycle

Metrics, Logs, and Alerts

Firewall

Backups

Billing

Data plane

Docs

Troubleshooting

For agent-side trace debugging, set ULTIPA_MCP_DEBUG=1 in the MCP env to log every tool call name and latency to stderr.