programmatic-mcp

A meta MCP server that:

• lists MCP servers available in a preset
• connects to preset servers on startup
• exposes approved server tools to execute_code() as JavaScript libraries
• stores console output separately through log tools

Config is read from $XDG_CONFIG_HOME/programmatic-mcp/config.json. If XDG_CONFIG_HOME is not set, it falls back to ~/.config/programmatic-mcp/config.json.

Run

node src/index.js
node src/index.js my-preset

The only optional argument is the preset name. If omitted, default is used.

Config

servers uses the same local or remote format as OpenCode MCP config.

presets decides which servers are visible and which tools from each server are allowed.

Server names must be valid JavaScript identifiers because execute_code() exposes them directly as globals.

Example:

{
  "servers": {
    "math": {
      "type": "local",
      "command": ["node", "/absolute/path/to/math-server.js"]
    },
    "docs": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:DOCS_TOKEN}"
      }
    }
  },
  "presets": {
    "default": {
      "servers": {
        "math": {
          "tools": ["add", "multiply"]
        },
        "docs": {
          "tools": ["search", "fetch_page"]
        }
      }
    },
    "math-only": ["math"]
  }
}

Accepted preset forms:

• "preset": ["server-a", "server-b"]
• "preset": { "servers": { "server-a": true } }
• "preset": { "servers": { "server-a": { "tools": ["tool1"] } } }

Tool rules:

• true, omitted tools, or "*" means all tools from that server
• tools: ["name"] restricts access to the listed tools
• false or enabled: false removes that server from the preset

OpenCode-style {env:NAME} and {file:path} substitutions are supported.

Exposed Tools

• list_servers
• list_tools
• execute_code
• fetch_logs
• clear_logs

Behavior

• preset servers are started when programmatic-mcp starts
• list_servers() returns which servers started successfully and any startup errors
• list_tools(server) returns only the tools allowed for that server in the preset
• execute_code(code) does not manage server lifecycle; it can only use servers that are already started
• console.log, console.info, console.warn, and console.error inside execute_code() are stored for fetch_logs()
• fetch_logs() drains the log buffer on read

execute_code

execute_code runs JavaScript as the body of an async function.

Started servers are injected as globals. Each allowed MCP tool becomes a function on that server object. Prefer underscore aliases when available.

Example:

return await math.add({ a: 2, b: 5 });

If the MCP tool returns structuredContent, that is what the JavaScript call resolves to. So the example above can return:

{
  "sum": 7
}

If a tool name is not a valid JavaScript identifier, prefer its underscore alias:

return await math.tool_name({ value: 1 });

The original tool name still works with bracket access:

return await math["tool-name"]({ value: 1 });