Connect an MCP client to ModuleX

Once you have published a server and a key, connecting a client takes two values: the server’s endpoint URL and an active key. This page has the endpoint and transport details, the authentication header, ready-to-paste configs for common clients, and the reference for every tool a connected client can call.

Endpoint and transport

A published server has a single endpoint, shown on its Overview and Connect tabs:

Endpoint

https://api.modulex.dev/mcp/serve/{server_id}

The server speaks the Model Context Protocol over Streamable HTTP: JSON-RPC requests sent as HTTP POST with Content-Type: application/json and Accept: application/json. It is stateless — each request stands alone — so there is no session to open or tear down. MCP clients handle the protocol for you; you only supply the URL and key, and the client discovers the available tools and calls them.

Authentication

A client authenticates with the server’s key (prefix mx_mcp_), sent as an X-API-Key header:

Request header

X-API-Key: mx_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Clients that send credentials as a bearer token can use Authorization instead:

Bearer alternative

Authorization: Bearer mx_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key is all a client sends. The server already knows its organization from the endpoint URL, so do not add an X-Organization-ID header — an MCP client authenticates with the server key alone. This is different from the ModuleX REST API, which uses an mx_live_ key plus X-Organization-ID; see API authentication for that surface.

Client configuration

Copy the config for your client from the server’s Connect tab, or use the templates below. Each uses the environment variable MODULEX_MCP_KEY for the key so you keep the secret out of the config file where the client supports it.

Claude Code
Cursor
Codex
Generic HTTP

Add the server to your MCP client configuration:

Claude Code

{
  "mcpServers": {
    "modulex": {
      "type": "http",
      "url": "https://api.modulex.dev/mcp/serve/8f2c1d4b-1a2b-4c3d-9e8f-6a5b4c3d2e1f",
      "headers": { "X-API-Key": "${MODULEX_MCP_KEY}" }
    }
  }
}

Set the key in your environment:

Set the key

export MODULEX_MCP_KEY='mx_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

See the Claude Code MCP docs for where the config lives.

Add the server to your MCP configuration:

Cursor

{
  "mcpServers": {
    "modulex": {
      "url": "https://api.modulex.dev/mcp/serve/8f2c1d4b-1a2b-4c3d-9e8f-6a5b4c3d2e1f",
      "headers": { "X-API-Key": "mx_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

See the Cursor MCP docs for the config location.

Add the server to your Codex configuration:

Codex

[mcp_servers.modulex]
url = "https://api.modulex.dev/mcp/serve/8f2c1d4b-1a2b-4c3d-9e8f-6a5b4c3d2e1f"
env_http_headers = { "X-API-Key" = "MODULEX_MCP_KEY" }
tool_timeout_sec = 180

Set MODULEX_MCP_KEY in your environment. See the Codex MCP docs for details.

Any MCP client that supports Streamable HTTP can connect with the URL and key:

Generic HTTP MCP client

{
  "transport": "streamable-http",
  "url": "https://api.modulex.dev/mcp/serve/8f2c1d4b-1a2b-4c3d-9e8f-6a5b4c3d2e1f",
  "headers": { "X-API-Key": "mx_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
}

If your client sends bearer tokens rather than a custom header, use "Authorization": "Bearer mx_mcp_…" instead of X-API-Key. See the MCP transports spec.

Replace the example URL with your server’s endpoint (from its Overview tab) and the placeholder with a real key. The modulex label is the name the client shows for the server — change it freely.

The published tools

A connected client lists the server’s tools automatically. What it sees depends on which tools you enabled when publishing: a fixed set of built-in tools, plus one tool per published workflow.

Built-in tools

The built-in tools cover your organization’s Files and Knowledge. Enable the ones you want per server.

Tool	Name	What it does
List available workflows	`workflows_list_available`	Lists the workflow tools this server publishes.
List files	`files_list`	Lists your organization’s Files.
Get file content	`files_get_content`	Reads the content of a File.
Write text file	`files_write_text`	Writes a text File.
Append text file	`files_append_text`	Appends text to a File.
List knowledge	`knowledge_list`	Lists your organization’s Knowledge bases.
Search knowledge	`knowledge_search`	Runs retrieval over a Knowledge base and returns matching context.

Enabled built-in tools are available to every active key on the server. File writes count against your organization’s existing Files quotas, and Search knowledge consumes credits like any managed retrieval.

Workflow tools

Each workflow you publish becomes one tool:

The tool name and description come from the workflow’s published metadata.
The input schema is the workflow’s published inputs, so the client knows what arguments to pass.
Calling the tool runs the deployed workflow with those inputs and returns its result. This consumes credits exactly as running the workflow in the app does.

Publish and deploy workflows from the builder; a client sees the current set the next time it lists tools.

Troubleshoot a connection

The client shows no tools or fails to connect

Confirm the endpoint URL is the server’s own (from its Overview tab), that the key is active and not expired, and that the client is configured for Streamable HTTP. Rotate the key from the Keys tab if you are unsure it is current.

A tool call returns an error instead of running

Calls that run a workflow or search Knowledge are billed. If your organization is out of credits or its plan does not permit the usage, the call returns an error result. See Usage gating & limits.

A workflow tool is missing

Only deployed workflows that the server publishes appear. Deploy the workflow and confirm it is included in the server’s published tools, then re-list tools in the client.

Next steps

Publish an MCP server

Create servers, choose tools, and manage keys and limits.

ModuleX MCP overview

What ModuleX MCP is and how it differs from custom MCP servers.

Deploy a workflow

Deploy a workflow so it can be published as an MCP tool.

Credits & metering

How workflow runs and Knowledge search are metered.

Overview

SDKs

Endpoints

Realtime

MCP server

Connect an MCP client

Endpoint and transport

Authentication

Client configuration

The published tools

Built-in tools

Workflow tools

Troubleshoot a connection

Next steps

Publish an MCP server

ModuleX MCP overview

Deploy a workflow

Credits & metering

​Endpoint and transport

​Authentication

​Client configuration

​The published tools

​Built-in tools

​Workflow tools

​Troubleshoot a connection

​Next steps

Publish an MCP server

ModuleX MCP overview

Deploy a workflow

Credits & metering

Endpoint and transport

Authentication

Client configuration

The published tools

Built-in tools

Workflow tools

Troubleshoot a connection

Next steps