Local MCP server

The local server is the npm-distributed counterpart to the hosted cloud server. It runs on your machine as a stdio child process, reads your OmniDimension API key from an environment variable, and proxies tool calls to the OmniDimension REST API.

Use the local server when you want:

• An API-key flow instead of OAuth (CI, automation, scripts).
• A stdio-only client that cannot speak HTTP MCP.
• A one-machine setup with no third-party hop.

For everything else, prefer the hosted cloud server.

Prerequisites

• Node.js 18 or later.
• An OmniDimension API key from omnidim.io/api-management.

One-command setup

npx -y @omnidim-ai/mcp-server setup

This detects every MCP client installed on your machine (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code) and writes the right config block into each. It also asks for your API key on first run, validates it, and stores it at ~/.config/omnidim/credentials for the next run.

When setup finishes, restart any client that was already open and the OmniDimension tools show up in its tool list.

Manual install

Skip this section if setup worked. Use these snippets only when you want to wire a single client by hand.

Claude Code

claude mcp add omnidim-local -e OMNIDIM_API_KEY=sk_xxx -- npx -y @omnidim-ai/mcp-server

Claude Desktop, Cursor, Windsurf

Add to the client's MCP config file:

{
  "mcpServers": {
    "omnidim-local": {
      "command": "npx",
      "args": ["-y", "@omnidim-ai/mcp-server"],
      "env": {
        "OMNIDIM_API_KEY": "sk_xxx"
      }
    }
  }
}

Config file locations:

VS Code

{
  "mcp": {
    "servers": {
      "omnidim-local": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@omnidim-ai/mcp-server"],
        "env": {
          "OMNIDIM_API_KEY": "sk_xxx"
        }
      }
    }
  }
}

How it works

On every tool call:

1. The MCP client spawns npx -y @omnidim-ai/mcp-server as a child process and pipes JSON-RPC over stdio.
2. The server validates the tool arguments against the OpenAPI-derived schema.
3. The server sends an HTTPS request to the OmniDimension REST API with Authorization: Bearer ${OMNIDIM_API_KEY}.
4. The response is shaped into the MCP tool result envelope and returned to the client.

The server never writes your key to disk and never sends it to any host other than the OmniDimension API.

Diagnostics

The package ships with a doctor command that prints a paste-ready report:

npx -y @omnidim-ai/mcp-server doctor

It lists detected clients, backend reachability, recent errors, and version info. It never prints your API key.

Tool call errors are appended to a local log at ~/.config/omnidim/logs/mcp.log (redacted, capped at 256 KB, never transmitted).

Telemetry

Anonymous usage data is sent to help us improve the package: package version, Node version, OS family, install count, and tool call counts by category. No API keys, no tool inputs or outputs, no file paths, no personal info.

Disable with:

npx -y @omnidim-ai/mcp-server telemetry disable

Source

@omnidim-ai/mcp-server on npm. Source at omnidim-mcp-server. Apache 2.0.