Copy page

AI & MCP

Local MCP server

@tomba-io/tomba-mcp-server is an MCP server that runs on your machine and calls the Tomba API with your key and secret. It provides the same 28 tools as the remote server. The remote MCP server needs no installation and also supports OAuth; Local server differences lists how the two servers behave differently.

Requirements

• Node.js 18.20 or later. Earlier versions stop at startup with SyntaxError: Unexpected token 'with'.
• A Tomba API key and secret. See Get your key and secret.

Run the server

Your MCP client usually starts the server for you, as shown in Configure a client. To check that the package installs and runs, print its version:

Code
npx -y @tomba-io/tomba-mcp-server --version

The server reads your credentials from two environment variables, and exits with Error: TOMBA_API_KEY and TOMBA_SECRET_KEY environment variables are required if either is missing:

It accepts these options:

Configure a client

In each example, replace ta_xxxx and ts_xxxx with your key and secret. Keep configuration files that contain your secret out of version control.

Claude Desktop

In Claude Desktop, open Settings → Developer and select Edit Config. The file is at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Add the server, then quit and restart Claude Desktop:

Code
{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "ta_xxxx",
                "TOMBA_SECRET_KEY": "ts_xxxx"
            }
        }
    }
}

The same mcpServers entry works in the configuration files of Cursor, Windsurf, Gemini CLI, and Cline; Connect a client says where each client keeps its file.

Claude Code

Code
claude mcp add --scope user tomba \
  -e TOMBA_API_KEY="$TOMBA_API_KEY" \
  -e TOMBA_SECRET_KEY="$TOMBA_SECRET_KEY" \
  -- npx -y @tomba-io/tomba-mcp-server

VS Code

Add the server to .vscode/mcp.json, or to the file that MCP: Open User Configuration opens. VS Code asks for the key and secret on first use and stores them securely:

Code
{
    "inputs": [
        {
            "type": "promptString",
            "id": "tomba-key",
            "description": "Tomba API key",
            "password": true
        },
        {
            "type": "promptString",
            "id": "tomba-secret",
            "description": "Tomba secret",
            "password": true
        }
    ],
    "servers": {
        "tomba": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "${input:tomba-key}",
                "TOMBA_SECRET_KEY": "${input:tomba-secret}"
            }
        }
    }
}

Zed

Run zed: open settings file and add the server under context_servers:

Code
{
    "context_servers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "ta_xxxx",
                "TOMBA_SECRET_KEY": "ts_xxxx"
            }
        }
    }
}

Verify the connection

1. The client lists 28 Tomba tools.
2. Ask the assistant to run the list_flags tool. A list of flags, even an empty one, means your credentials work.

When the server starts over stdio, it writes Tomba MCP server running on stdio to its error output. Claude Desktop saves that output in mcp-server-tomba.log, in ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows.

HTTP transport

With --transport http, the server listens on the given port and serves Streamable HTTP at /mcp, with a health check at /health:

Code
TOMBA_API_KEY="ta_xxxx" TOMBA_SECRET_KEY="ts_xxxx" \
  npx -y @tomba-io/tomba-mcp-server --transport http --port 3000

Clients connect to http://localhost:3000/mcp. The server handles one MCP session per process: a second client, or a client that reconnects, gets HTTP 500 until you restart the server.

Troubleshooting