# Local MCP server (/docs/mcp/local-server)

> Run the OmniDimension MCP server locally as a stdio child process. Distributed as @omnidim-ai/mcp-server on npm. One command auto-configures every detected MCP client.

The local server is the npm-distributed counterpart to the hosted [cloud server](/docs/mcp/connect). 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](/docs/mcp/connect).

## Prerequisites [#prerequisites]

* Node.js 18 or later.
* An OmniDimension API key from [omnidim.io/api-management](https://omnidim.io/api-management).

## One-command setup [#one-command-setup]

```bash
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 [#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-code]

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

### Claude Desktop, Cursor, Windsurf [#claude-desktop-cursor-windsurf]

Add to the client's MCP config file:

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

Config file locations:

| Client                   | Path                                                              |
| ------------------------ | ----------------------------------------------------------------- |
| Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Cursor                   | `~/.cursor/mcp.json`                                              |
| Windsurf                 | `~/.codeium/windsurf/mcp_config.json`                             |

### VS Code [#vs-code]

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

## How it works [#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 [#diagnostics]

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

```bash
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 [#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:

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

## Source [#source]

[`@omnidim-ai/mcp-server`](https://www.npmjs.com/package/@omnidim-ai/mcp-server) on npm. Source at [`omnidim-mcp-server`](https://github.com/Omnidim/omnidim-mcp-server). Apache 2.0.