MCP server

#Overview

Converge runs a Model Context Protocol (MCP) server, so any MCP-compatible AI assistant can run Converge engines and read your saved projects. Your MCP client connects with an API key and acts as you: your permissions, your licences and your seats.

#Connect

1. On Integrations > API keys, create a key with the engine:run scope. Add projects:read if the assistant should read projects.

2. In your MCP client, add a remote server with this URL:

   textCopy

   https://<your-app-host>/v1/mcp

3. Add the header:

   httpCopy

   Authorization: Bearer <your key>

4. Ask it something, for example: "Run a nodal analysis for a 9,500 ft oil well at 3,200 psia and tell me the operating rate."

Integrations > AI assistants (MCP) shows the exact URL for your deployment and both configurations below, filled in.

#Configuration

#Remote server (URL)

For an MCP client that accepts a server URL and headers:

{
  "mcpServers": {
    "converge": {
      "type": "http",
      "url": "https://<your-app-host>/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${CONVERGE_API_KEY}"
      }
    }
  }
}

Field names vary between MCP clients; what matters is the URL and the Authorization header. If your client does not read environment variables, replace ${CONVERGE_API_KEY} with the key.

#Local bridge (stdio)

For an MCP client that only starts local servers, use the bridge: one file, no dependencies, Node.js 18 or later. Download it with Download bridge on the MCP tab, or from:

https://<your-app-host>/mcp/converge-mcp-bridge.mjs

{
  "mcpServers": {
    "converge": {
      "command": "node",
      "args": ["/path/to/converge-mcp-bridge.mjs"],
      "env": {
        "CONVERGE_MCP_URL": "https://<your-app-host>/v1/mcp",
        "CONVERGE_API_KEY": "cvg_your_key_here"
      }
    }
  }
}

The bridge reads newline-delimited JSON-RPC messages on stdin, posts each to the remote server with your key, and writes each response as one line on stdout. Diagnostics go to stderr. It exits if either environment variable is missing.

#Transport

The protocol version is negotiated on initialize: the client's version if supported, otherwise 2025-11-25. Later requests may send MCP-Protocol-Version; an unsupported value is a 400. A POST that holds only notifications or responses gets 202 with no body.

Supported methods: initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read.

#Tools

tools/list returns:

Each tool carries its JSON Schema input and is marked read-only and idempotent. Engine tools use field units (psia, degF, STB/d, Mscf/d, ft) unless the input sets "units": "metric". Unknown input keys are refused.

A tool result is text (cut at 100,000 characters; call the REST API for a larger result). For protocol 2025-06-18 and later, object results also come back as structuredContent.

When a tool fails (bad input, no seat, missing scope, out of range) the result has isError: true and a message with the error code, so the assistant can read it, fix the input and try again. An unknown tool or malformed params is a JSON-RPC error.

#Resources

With projects:read, saved projects are resources:

converge://projects/{id}

resources/list lists them; resources/read returns the project as application/json.

#Seats and limits

Every call holds your Integrations seat, and an engine tool also holds its module's seat, exactly like opening the module in the app. Seats are released 3 minutes after the last call. If every seat is taken, the tool error names who holds them. MCP and REST share one rate limit: 120 requests a minute per key. See REST API.

#Related

• API keys
• REST API
• Scripting SDK
• AI Engineer