### Install and Run callmux

Source: https://context7.com/edimuj/callmux/llms.txt

Install callmux globally or run it directly using npx. The setup wizard can guide you through interactive configuration.

```bash
npx -y callmux -- npx -y @modelcontextprotocol/server-github
```

```bash
npm install -g callmux
```

```bash
npx -y callmux setup
```

--------------------------------

### Interactive CallMux Setup

Source: https://github.com/edimuj/callmux/blob/main/README.md

Run this command to start the interactive setup wizard for CallMux. The wizard helps configure servers, caching, meta-only mode, and client attachments.

```bash
npx -y callmux setup
```

--------------------------------

### Install and Start Callmux Daemon

Source: https://github.com/edimuj/callmux/blob/main/README.md

Install callmux as a system daemon for persistent background operation and automatic startup.

```bash
callmux daemon install --start --enable
```

--------------------------------

### Install Callmux Daemon

Source: https://github.com/edimuj/callmux/blob/main/docs/cli-reference.md

Installs the Callmux daemon as a service, starting and enabling it. Use `--system` for system-wide installation on Linux or `daemon status`, `daemon logs`, and `daemon restart` to manage the service.

```bash
callmux daemon install --config ~/.config/callmux/config.json --start --enable
```

```bash
callmux daemon status
```

```bash
callmux daemon logs
```

```bash
callmux daemon restart
```

--------------------------------

### Install Callmux with npx

Source: https://github.com/edimuj/callmux/blob/main/README.md

Use npx for immediate execution without global installation. This command also launches an MCP server for GitHub.

```bash
npx -y callmux -- npx -y @modelcontextprotocol/server-github
```

--------------------------------

### Full Example Configuration

Source: https://github.com/edimuj/callmux/blob/main/docs/config-reference.md

This example demonstrates a complete CallMux configuration, including server definitions, recipes, caching policies, security settings, and abuse controls. It shows how to set up integrations with GitHub and a remote API, define custom workflows, and enforce access policies.

```json
{
  "$schema": "https://raw.githubusercontent.com/edimuj/callmux/main/schema.json",
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" },
      "tools": ["create_issue", "get_issue", "list_issues", "search_issues"],
      "maxConcurrency": 5,
      "cachePolicy": { "allowTools": ["get_*", "list_*"] }
    },
    "remote-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer sk-..." },
      "transport": "streamable-http"
    }
  },
  "recipes": {
    "open_bug": {
      "description": "Create a labeled bug issue",
      "mode": "call",
      "server": "github",
      "tool": "create_issue",
      "arguments": {
        "title": { "$param": "title" },
        "body": { "$param": "body" },
        "labels": ["bug"]
      }
    }
  },
  "cacheTtlSeconds": 60,
  "maxCacheEntries": 1000,
  "cachePolicy": { "denyTools": ["create_*"] },
  "maxConcurrency": 20,
  "connectTimeoutMs": 30000,
  "callTimeoutMs": 180000,
  "strictStartup": false,
  "metaOnly": false,
  "descriptionMaxLength": 80,
  "responseShield": {
    "maxResultBytes": 65536,
    "maxStoredResults": 100,
    "denyTools": ["download_*"]
  },
  "auth": {
    "mode": "bearer",
    "tokens": [{ "id": "ops", "hash": "scrypt$16384$8$1$<salt>$<derivedKey>" }],
    "allowUnauthenticatedHealth": false
  },
  "authorization": {
    "defaultEffect": "deny",
    "rules": [
      { "id": "ops-all", "effect": "allow", "principals": ["bearer:ops"], "tools": ["*"] },
      { "id": "agents-read", "effect": "allow", "principals": ["oidc:*"], "tools": ["github__get_*", "github__list_*"] }
    ]
  },
  "abuseControls": {
    "globalRequestsPerMinute": 1200,
    "principalRequestsPerMinute": 240,
    "principalMaxInFlight": 20,
    "cidrAllowlist": ["127.0.0.1/32", "::1/128"]
  },
  "auditLog": {
    "enabled": true,
    "includeRequestBody": false,
    "maxPayloadChars": 4096
  },
  "metrics": {
    "enabled": true,
    "path": "/metrics",
    "allowUnauthenticated": false
  },
  "dashboard": {
    "enabled": true,
    "path": "/dashboard",
    "maxEvents": 500
  }
}
```

--------------------------------

### Programmatic API Setup with Callmux (Node.js/TypeScript)

Source: https://context7.com/edimuj/callmux/llms.txt

Demonstrates importing and using core Callmux classes and utilities in a Node.js/TypeScript environment for loading configurations, running diagnostics, creating proxies, and starting listeners.

```typescript
import {
  CallmuxProxy,
  CallmuxListener,
  UpstreamManager,
  CallCache,
  loadConfig,
  runDoctor,
} from "callmux";

// Load and validate a config file
const config = await loadConfig("/path/to/config.json");

// Run doctor checks against all configured servers
const report = await runDoctor(config);
console.log(report.servers); // per-server connectivity results

// Create a proxy for a single downstream server
const proxy = new CallmuxProxy({
  servers: {
    github: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN ?? "" },
    },
  },
  cacheTtlSeconds: 60,
});

// Start a shared HTTP listener
const listener = new CallmuxListener({
  port: 4860,
  host: "127.0.0.1",
  config,
});
await listener.start();
console.log("callmux listener running on http://localhost:4860");
```

--------------------------------

### callmux Configuration File Example

Source: https://context7.com/edimuj/callmux/llms.txt

Example of a callmux configuration file, defining servers, caching, and concurrency settings. Supports standard MCP format and additional callmux-specific options.

```json
{
  "$schema": "https://raw.githubusercontent.com/edimuj/callmux/main/schema.json",
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" },
      "tools": ["create_issue", "get_issue", "list_issues", "search_issues"],
      "maxConcurrency": 5,
      "cachePolicy": { "allowTools": ["get_*", "list_*"] }
    },
    "remote-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer sk-..." },
      "transport": "streamable-http"
    }
  },
  "cacheTtlSeconds": 60,
  "maxCacheEntries": 1000,
  "maxConcurrency": 20,
  "callTimeoutMs": 180000,
  "metaOnly": false,
  "strictStartup": false
}
```

--------------------------------

### Start Callmux Listener and Access Dashboard

Source: https://context7.com/edimuj/callmux/llms.txt

Command to start the Callmux listener on a specified port and with a configuration file. Includes the URL to access the dashboard.

```bash
callmux --listen 4860 --config ~/.config/callmux/config.json
# Visit: http://localhost:4860/dashboard
```

--------------------------------

### Install Callmux Globally

Source: https://github.com/edimuj/callmux/blob/main/README.md

Install the callmux package globally for command-line access.

```bash
npm install -g callmux
```

--------------------------------

### Start callmux Listener

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Starts the callmux listener on a specified port. By default, it binds to localhost. Use `--host 0.0.0.0` to expose it on all interfaces.

```bash
callmux --listen 4860
```

```bash
callmux --listen 4860 --host 0.0.0.0
```

--------------------------------

### Start Callmux Shared Server

Source: https://github.com/edimuj/callmux/blob/main/README.md

Launch callmux in listen mode to enable shared server capabilities, reducing process and memory overhead.

```bash
callmux --listen 4860
```

--------------------------------

### Configure Callmux Client (Claude Desktop)

Source: https://context7.com/edimuj/callmux/llms.txt

Configure Claude Desktop to connect to a callmux listener using a command to start the bridge.

```json
// Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "callmux": {
      "command": "npx",
      "args": ["-y", "callmux", "bridge", "--url", "http://localhost:4860/mcp"]
    }
  }
}
```

--------------------------------

### Install callmux as a Background Daemon

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Installs and enables callmux as a persistent background daemon. This ensures the listener remains active across sessions. Use `--dry-run` to preview changes and `--force` to overwrite existing managed files.

```bash
callmux daemon install --config ~/.config/callmux/config.json --start --enable
```

--------------------------------

### Enabling Meta-Only Mode

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Meta-Only Mode can be enabled through the configuration file, a CLI flag, or the setup wizard.

```APIDOC
## Enabling Meta-Only Mode

Three ways:

**Config file:**
```json
{
  "metaOnly": true,
  "descriptionMaxLength": 80
}
```

**CLI flag:**
```bash
callmux --meta-only
```

**Setup wizard:**
```bash
callmux setup   # offers meta-only as an option
```
```

--------------------------------

### Run Callmux in Listener Mode

Source: https://github.com/edimuj/callmux/blob/main/docs/dashboard.md

Execute the callmux command with the --listen flag to start it in listener mode, making the dashboard accessible. Ensure the --config flag points to your configuration file.

```bash
callmux --listen 4860 --config ~/.config/callmux/config.json
```

--------------------------------

### Caddy Reverse Proxy Configuration for Callmux

Source: https://context7.com/edimuj/callmux/llms.txt

Example Caddyfile configuration for setting up a reverse proxy to Callmux, including redirection and handling requests for the Callmux path.

```caddyfile
redir /callmux /callmux/ 301
handle /callmux/* {
    reverse_proxy localhost:4860
}
```

--------------------------------

### Start Callmux Shared Server Listener

Source: https://context7.com/edimuj/callmux/llms.txt

Run callmux as a persistent HTTP listener to share downstream servers, cache, and infrastructure across agent sessions. Use `--host 0.0.0.0` to expose on all interfaces.

```bash
# Start the listener
callmux --listen 4860

# Expose on all interfaces (requires auth config)
callmux --listen 4860 --host 0.0.0.0

# Install as a background daemon (auto-selects systemd or LaunchAgent)
callmux daemon install --config ~/.config/callmux/config.json --start --enable

# Daemon management
callmux daemon status
callmux daemon logs
callmux daemon restart
callmux daemon stop
```

--------------------------------

### Run Callmux as Shared Listener

Source: https://github.com/edimuj/callmux/blob/main/docs/cli-reference.md

Start Callmux as a shared listener on a specified port. Use '--host 0.0.0.0' to expose it on all network interfaces, useful for remote access.

```bash
callmux --listen 4860
```

```bash
callmux --listen 4860 --host 0.0.0.0   # expose on all interfaces (e.g. Tailscale)
```

--------------------------------

### Caddy Configuration: Prefix Stripped

Source: https://github.com/edimuj/callmux/blob/main/docs/dashboard.md

Example Caddyfile configuration for a reverse proxy that strips the '/callmux' path prefix before forwarding requests to callmux.

```caddyfile
redir /callmux /callmux/ 301
handle_path /callmux/* {
	reverse_proxy localhost:4860
}
```

--------------------------------

### Caddy Configuration: Prefix Preserved

Source: https://github.com/edimuj/callmux/blob/main/docs/dashboard.md

Example Caddyfile configuration for a reverse proxy that preserves the '/callmux' path prefix when forwarding requests to callmux.

```caddyfile
redir /callmux /callmux/ 301
handle /callmux/* {
	reverse_proxy localhost:4860
}
```

--------------------------------

### Override Response Shielding Per Server

Source: https://github.com/edimuj/callmux/blob/main/docs/config-reference.md

Configure response shielding settings on a per-server basis to override global defaults. This example disables response shielding for the 'github' server.

```json
{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "responseShield": {
        "enabled": false
      }
    }
  }
}
```

--------------------------------

### Add Server with Tool Scoping

Source: https://github.com/edimuj/callmux/blob/main/README.md

Use this command to add a server and specify which tools it should expose. This is useful for per-server tool filtering for any client.

```bash
callmux server add github --tools "create_issue,get_issue,list_issues" -- npx -y @modelcontextprotocol/server-github
```

--------------------------------

### Callmux Get Result Fallback

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

If `callmux_get_result` is deferred, use the fallback mechanism provided in `_callmux.retrieval.viaCallmuxCall.arguments` to invoke it via `callmux_call`.

```json
// callmux_call
{
  "tool": "callmux_get_result",
  "arguments": {
    "ref": "r_...",
    "offset": 0,
    "limit": 50
  }
}
```

--------------------------------

### Configure HTTP Server with URL

Source: https://github.com/edimuj/callmux/blob/main/docs/config-reference.md

Use 'url' instead of 'command' for remote MCP servers. Transport is auto-detected but can be forced to 'sse' or 'streamable-http'. 'strictStartup' can be set to true to fail startup if any downstream server fails.

```json
{
  "url": "http://mcp.example.com",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  "tools": ["get_user", "list_items"],
  "maxConcurrency": 10,
  "callTimeoutMs": 5000,
  "requestBodyMaxBytes": 1024,
  "cachePolicy": {},
  "responseShield": {}
}
```

--------------------------------

### Various File and Data Reference Types

Source: https://context7.com/edimuj/callmux/llms.txt

Demonstrates different ways to reference external data, including JSON, YAML, and text content, with options for size limits and joining text lines.

```json
{
  "arguments": {
    "body":    { "$file": "/tmp/issue.md", "maxBytes": 2000000 },
    "config":  { "$jsonFile": "/tmp/settings.json" },
    "schema":  { "$yamlFile": "/tmp/api-schema.yaml" },
    "message": {
      "$text": {
        "lines": ["## Summary", "", "| Field | Value |", "| --- | --- |", "| Status | OK |"],
        "join": "\n"
      }
    }
  }
}
```

--------------------------------

### Print Client Snippets

Source: https://github.com/edimuj/callmux/blob/main/docs/cli-reference.md

Generate ready-to-paste snippets for client configuration. You can specify a remote server URL and choose between a direct connection or a bridge.

```bash
callmux client print codex --url http://localhost:4860/mcp
```

```bash
callmux client print codex --url http://localhost:4860/mcp --bridge
```

```bash
callmux client print claude --url http://localhost:4860/mcp
```

--------------------------------

### Configure Caching via CLI

Source: https://context7.com/edimuj/callmux/llms.txt

Enable caching directly from the command line with TTL and allow/deny policies.

```bash
callmux --cache 60 --cache-allow "get_*,list_*" --cache-deny "get_secret" -- npx -y @modelcontextprotocol/server-github
```

--------------------------------

### Example Callmux status response shape

Source: https://context7.com/edimuj/callmux/llms.txt

This JSON object illustrates the typical structure of a response from `callmux_status`, detailing server connectivity, tool counts, cache statistics, and more.

```json
{
  "mode": "listener",
  "servers": {
    "github": { "status": "connected", "toolCount": 4, "tools": ["create_issue", "get_issue"] }
  },
  "failedServers": [],
  "cache": { "entries": 12, "maxEntries": 1000, "ttlSeconds": 60 },
  "responseStore": { "activeRefs": 3, "capacity": 100, "storedBytes": 49152 },
  "toolSuiteGeneration": 1
}
```

--------------------------------

### Generate Client Configuration Snippets

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Commands to generate client configuration snippets for Codex and Claude, specifying the listener URL and whether to use the stdio bridge.

```bash
callmux client print codex --url http://localhost:4860/mcp
```

```bash
callmux client print codex --url http://localhost:4860/mcp --bridge
```

```bash
callmux client print claude --url http://localhost:4860/sse
```

--------------------------------

### Callmux Get Result

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Paginate through large downstream results using `callmux_get_result` with a `ref` and pagination parameters. The response includes `_callmux.shape` and `_callmux.retrieval` for data inspection and further calls.

```json
// callmux_get_result
{
  "ref": "r_...",
  "offset": 0,
  "limit": 50,
  "fields": ["id", "name"]
}
```

--------------------------------

### Tool Naming with Multiple Servers (Using Server Field)

Source: https://context7.com/edimuj/callmux/llms.txt

Alternatively, use the `server` field to specify the target server, avoiding the need to manage namespace prefixes manually.

```json
{
  "calls": [
    { "server": "github", "tool": "create_issue", "arguments": { "title": "Bug" } },
    { "server": "linear", "tool": "create_issue", "arguments": { "title": "Bug" } }
  ]
}
```

--------------------------------

### Enable Meta-Only Mode via CLI

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Activate Meta-Only mode directly from the command line using the `--meta-only` flag.

```bash
callmux --meta-only
```

--------------------------------

### Configure Claude Desktop Client

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Configuration for Claude Desktop to use the callmux stdio bridge. This is useful if the app has a minimal PATH. Add this to your `claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "callmux": {
      "command": "npx",
      "args": ["-y", "callmux", "bridge", "--url", "http://localhost:4860/mcp"]
    }
  }
}
```

--------------------------------

### Control Callmux Daemon

Source: https://context7.com/edimuj/callmux/llms.txt

Manage the Callmux daemon service, including installation, status checks, log retrieval, restarting, and uninstallation. Use `--dry-run` for uninstallation to preview actions.

```bash
callmux daemon install --config ~/.config/callmux/config.json --start --enable
```

```bash
callmux daemon status
```

```bash
callmux daemon logs
```

```bash
callmux daemon restart
```

```bash
callmux daemon uninstall --dry-run
```

--------------------------------

### Configure tool discovery descriptions

Source: https://context7.com/edimuj/callmux/llms.txt

When using `callmux_status` in meta-only mode for tool discovery, enable descriptions and set `descriptionMaxLength` to control the length of tool descriptions returned.

```json
{
  "descriptions": true,
  "descriptionMaxLength": 80
}
```

--------------------------------

### Configure Local and Remote Servers

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Define both local stdio servers and remote MCP servers with their respective configurations, including URLs and headers for remote connections.

```json
{
  "servers": {
    "local-github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "remote-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-..."
      }
    }
  }
}
```

--------------------------------

### Introspect running Callmux instance

Source: https://context7.com/edimuj/callmux/llms.txt

Use `callmux_status` to get information about the running Callmux instance, including connected servers, tool counts, cache state, and session diagnostics. An empty JSON object `{}` retrieves the default status.

```json
{}
```

--------------------------------

### Configure Caching Policies

Source: https://context7.com/edimuj/callmux/llms.txt

Enable result caching with a TTL and optional allow/deny policies per tool name pattern. Per-server overrides are also supported.

```json
{
  "cacheTtlSeconds": 60,
  "maxCacheEntries": 1000,
  "cachePolicy": {
    "allowTools": ["get_*", "list_*", "search_*"],
    "denyTools": ["get_secret", "get_credentials"]
  },
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "cachePolicy": {
        "denyTools": ["create_*", "update_*", "delete_*"]
      }
    }
  }
}
```

--------------------------------

### Define Reusable Workflows with Recipes

Source: https://context7.com/edimuj/callmux/llms.txt

Define multi-step workflows in JSON configuration using `$param` for runtime substitution. Supports 'call', 'parallel', and 'pipeline' modes.

```json
{
  "recipes": {
    "open_bug": {
      "description": "Create a labeled bug issue",
      "mode": "call",
      "server": "github",
      "tool": "create_issue",
      "arguments": {
        "title": { "$param": "title" },
        "body": { "$param": "body" },
        "labels": ["bug"],
        "assignees": ["triage-team"]
      }
    },
    "triage_pair": {
      "description": "Fetch two issues side-by-side for comparison",
      "mode": "parallel",
      "calls": [
        { "server": "github", "tool": "get_issue", "arguments": { "issue_number": { "$param": "first" } } },
        { "server": "github", "tool": "get_issue", "arguments": { "issue_number": { "$param": "second" } } }
      ]
    },
    "search_and_analyze": {
      "description": "Search issues then generate analysis report",
      "mode": "pipeline",
      "steps": [
        { "tool": "search_issues", "arguments": { "query": { "$param": "query" } } },
        { "tool": "analyze_results", "arguments": { "format": "markdown" }, "inputMapping": { "data": "$json" } }
      ]
    }
  }
}
```

--------------------------------

### CLI: Modify Server Tools

Source: https://context7.com/edimuj/callmux/llms.txt

Use the `server set` command to add new tools to an existing server configuration.

```bash
callmux server set github --add-tool search_issues
```

--------------------------------

### Callmux Status (No Args)

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

In Meta-Only mode, use `callmux_status` without arguments to discover available servers, their tool counts, cache state, and current mode.

```json
// callmux_status (no args)
-> Returns: server names, tool counts, cache state, mode
```

--------------------------------

### Define a Pipeline Recipe for Chained Steps

Source: https://github.com/edimuj/callmux/blob/main/docs/recipes.md

This recipe defines a pipeline where the output of the 'search_issues' tool is piped as input to the 'analyze' tool. It uses `$json` to map the entire JSON output of the previous step.

```json
{
  "recipes": {
    "search_and_analyze": {
      "description": "Search issues then analyze results",
      "mode": "pipeline",
      "steps": [
        { "tool": "search_issues", "arguments": { "query": { "$param": "query" } } },
        { "tool": "analyze", "arguments": {}, "inputMapping": { "data": "$json" } }
      ]
    }
  }
}
```

--------------------------------

### Agent Call for a Call Recipe

Source: https://github.com/edimuj/callmux/blob/main/docs/recipes.md

An agent calls the 'open_bug' recipe by providing the recipe name and the required arguments for the placeholders.

```json
{
  "recipe": "open_bug",
  "arguments": {
    "title": "Crash on startup",
    "body": "Steps to reproduce..."
  }
}
```

--------------------------------

### Tool Naming with Single Server

Source: https://context7.com/edimuj/callmux/llms.txt

When only one server is configured, tools retain their original names. This simplifies direct tool calls.

```json
{ "tool": "create_issue", "arguments": { "title": "Bug" } }
```

--------------------------------

### CLI: Server Management Commands

Source: https://context7.com/edimuj/callmux/llms.txt

Common CLI commands for managing Callmux servers, including listing, removing, and testing server configurations.

```bash
callmux server list
```

```bash
callmux server remove github
```

```bash
callmux server test github
```

--------------------------------

### Configure Caching Behavior

Source: https://github.com/edimuj/callmux/blob/main/docs/config-reference.md

Enables and configures caching for tool calls. 'allowTools' and 'denyTools' use wildcards for fine-grained control. Oldest entries are evicted when 'maxCacheEntries' is reached.

```json
{
  "cacheTtlSeconds": 60,
  "maxCacheEntries": 1000,
  "cachePolicy": {
    "allowTools": ["get_*", "list_*", "search_*"],
    "denyTools": ["get_secret"]
  }
}
```

--------------------------------

### CLI: Add GitHub Server

Source: https://context7.com/edimuj/callmux/llms.txt

Add a GitHub server to Callmux using the CLI. The `--tools` flag can specify which tools are available for this server.

```bash
callmux server add github -- npx -y @modelcontextprotocol/server-github
```

```bash
callmux server add github --tools "create_issue,get_issue,list_issues" -- npx -y @modelcontextprotocol/server-github
```

--------------------------------

### Define a tool call pipeline with input mapping

Source: https://context7.com/edimuj/callmux/llms.txt

Use `callmux_pipeline` to chain tool calls, where the output of one step feeds into the next via `inputMapping`. The output of step N is passed to step N+1 as specified by the mapping.

```json
{
  "steps": [
    {
      "server": "github",
      "tool": "search_issues",
      "arguments": { "query": "is:open label:bug milestone:v2.0" }
    },
    {
      "server": "github",
      "tool": "create_issue",
      "arguments": { "title": "Bug triage report" },
      "inputMapping": { "body": "$json" }
    }
  ]
}
```

--------------------------------

### Tool Naming with Multiple Servers (Namespaced)

Source: https://context7.com/edimuj/callmux/llms.txt

When multiple servers are configured, tools are automatically namespaced using the `server__tool` format to prevent naming collisions.

```json
{
  "calls": [
    { "tool": "github__create_issue", "arguments": { "title": "Bug", "repo": "myrepo" } },
    { "tool": "linear__create_issue", "arguments": { "title": "Bug", "teamId": "ENG" } }
  ]
}
```

--------------------------------

### Callmux Search Tools

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Use `callmux_search_tools` with a query to find matching callable tool names, servers, descriptions, scores, and input field hints. Specify `server` to narrow results.

```json
// callmux_search_tools
{
  "query": "github issue",
  "limit": 5
}
-> Returns matching callable tool names, servers, descriptions, scores, and input field hints
```

--------------------------------

### Preview a named recipe without execution

Source: https://context7.com/edimuj/callmux/llms.txt

Use `callmux_recipe_dry_run` to preview the execution plan of a named recipe without actually running it. This is useful for validating the recipe's arguments and intended actions.

```json
{
  "recipe": "search_and_analyze",
  "arguments": { "query": "is:open label:regression milestone:v3.0" }
}
```

--------------------------------

### Dev Release Profile Configuration

Source: https://github.com/edimuj/callmux/blob/main/docs/security/2026-04-30-release-profiles.md

Use this JSON configuration for local development environments. It enables minimal security controls, allowing unauthenticated health checks.

```json
{
  "servers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
  },
  "auth": {
    "mode": "bearer",
    "tokens": [{ "id": "dev", "hashRef": "env:CALLMUX_DEV_HASH" }],
    "allowUnauthenticatedHealth": true
  },
  "metrics": {
    "enabled": false
  }
}
```

--------------------------------

### Configure Codex Client (Streamable HTTP)

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Configuration for Codex to connect to the callmux shared listener via streamable HTTP. Add this to your `~/.codex/config.toml` or project `.codex/config.toml`.

```toml
[mcp_servers.callmux]
url = "http://localhost:4860/mcp"
```

--------------------------------

### Filter Tools on an Existing Server

Source: https://github.com/edimuj/callmux/blob/main/docs/cli-reference.md

Modify an existing server's configuration to add specific tools. This allows fine-grained control over which tools are exposed by the server.

```bash
callmux server set github --add-tool search_issues --add-tool get_issue
```

--------------------------------

### Callmux Status with Descriptions

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Retrieve tool names and truncated descriptions for all exposed tools by calling `callmux_status` with `descriptions: true`. Adjust verbosity with `descriptionMaxLength`.

```json
// callmux_status with descriptions
{
  "descriptions": true,
  "descriptionMaxLength": 80
}
-> Returns: tool names + truncated descriptions per server
```

--------------------------------

### Define a Call Recipe for Creating Issues

Source: https://github.com/edimuj/callmux/blob/main/docs/recipes.md

This recipe defines a single tool call to create an issue with a predefined 'bug' label. It uses `$param` placeholders for dynamic arguments like title and body.

```json
{
  "recipes": {
    "open_bug": {
      "description": "Create a labeled bug issue",
      "mode": "call",
      "server": "github",
      "tool": "create_issue",
      "arguments": {
        "title": { "$param": "title" },
        "body": { "$param": "body" },
        "labels": ["bug"]
      }
    }
  }
}
```

--------------------------------

### Target Specific Servers in Multi-Server Calls

Source: https://github.com/edimuj/callmux/blob/main/docs/config-reference.md

When using multiple servers, tools are namespaced (e.g., `github__create_issue`). Use the `server` field in meta-tool calls to direct the call to a specific server.

```json
{
  "calls": [
    { "server": "github", "tool": "get_issue", "arguments": { "number": 42 } },
    { "server": "linear", "tool": "get_issue", "arguments": { "id": "ENG-123" } }
  ]
}
```

--------------------------------

### callmux_batch Meta-Tool Usage

Source: https://context7.com/edimuj/callmux/llms.txt

Apply the same tool call to multiple items in a single turn. Optimized for bulk operations with the same tool.

```json
{
  "server": "github",
  "tool": "create_issue",
  "items": [
    { "arguments": { "title": "Bug: login crash", "body": "Crashes on iOS 17", "labels": ["bug"] } },
    { "arguments": { "title": "Bug: dark mode", "body": "Colors wrong in dark mode", "labels": ["bug"] } },
    { "arguments": { "title": "Feature: export CSV", "body": "Users want CSV export", "labels": ["enhancement"] } }
  ]
}
```

```json
{
  "tool": "read_file",
  "items": [
    { "arguments": { "path": "src/index.ts" }, "cwd": "/work/project-a" },
    { "arguments": { "path": "src/index.ts" }, "cwd": "/work/project-b" }
  ]
}
```

--------------------------------

### Enable Meta-Only Mode in Config

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Configure Meta-Only mode by setting `metaOnly` to `true` in the Callmux configuration file. `descriptionMaxLength` can also be set to control tool description verbosity.

```json
{
  "metaOnly": true,
  "descriptionMaxLength": 80
}
```

--------------------------------

### Staging Release Profile Configuration

Source: https://github.com/edimuj/callmux/blob/main/docs/security/2026-04-30-release-profiles.md

This JSON configuration is for staging environments, enforcing OIDC JWT authentication and enabling authorization, abuse controls, and audit logging with request body redaction.

```json
{
  "auth": {
    "mode": "oidc_jwt",
    "issuer": "https://id.staging.example.com",
    "audience": "callmux",
    "jwksUri": "https://id.staging.example.com/.well-known/jwks.json"
  },
  "authorization": {
    "defaultEffect": "deny",
    "rules": [
      { "id": "ops", "effect": "allow", "principals": ["oidc_jwt:ops-*"], "tools": ["*"] }
    ]
  },
  "abuseControls": {
    "globalRequestsPerMinute": 1200,
    "principalRequestsPerMinute": 240,
    "principalMaxInFlight": 20
  },
  "auditLog": {
    "enabled": true,
    "includeRequestBody": true,
    "maxPayloadChars": 4096
  },
  "metrics": {
    "enabled": true,
    "path": "/metrics",
    "allowUnauthenticated": false
  }
}
```

--------------------------------

### Validate Configuration and Connectivity with Callmux Doctor

Source: https://context7.com/edimuj/callmux/llms.txt

Use `callmux doctor` to validate your configuration and check connectivity to configured servers. Options include specifying a URL, current working directory, and JSON output.

```bash
callmux doctor
```

```bash
callmux doctor --url http://localhost:4860/mcp --cwd "$PWD"
```

```bash
callmux doctor --json
```

--------------------------------

### Configure Prometheus Metrics

Source: https://github.com/edimuj/callmux/blob/main/docs/enterprise.md

Enable the Prometheus metrics endpoint to expose operational metrics. Configure the metrics path and whether unauthenticated access is allowed.

```json
{
  "metrics": {
    "enabled": true,
    "path": "/metrics",
    "allowUnauthenticated": false
  }
}
```

--------------------------------

### callmux Daemon Management Commands

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Provides essential commands for managing the callmux daemon, including checking status, viewing logs, restarting, stopping, and uninstalling.

```bash
callmux daemon status
```

```bash
callmux daemon logs
```

```bash
callmux daemon restart
```

```bash
callmux daemon stop
```

```bash
callmux daemon uninstall
```

--------------------------------

### Manage Callmux Clients

Source: https://context7.com/edimuj/callmux/llms.txt

Commands for attaching, detaching, and checking the status of Callmux clients. Use `--yes` to bypass confirmation prompts. Options like `--url` and `--bridge` can be specified for specific client configurations.

```bash
callmux client attach claude --yes
```

```bash
callmux client attach codex --url http://localhost:4860/mcp --bridge --yes
```

```bash
callmux client detach claude --yes
```

```bash
callmux client status claude
```

```bash
callmux client print codex --url http://localhost:4860/mcp --bridge
```

--------------------------------

### Reference Raw File Content

Source: https://github.com/edimuj/callmux/blob/main/docs/config-reference.md

Use the `$file` schema to include the raw content of a file as an argument. You can optionally override the default `maxBytes` limit.

```json
{
  "body": { "$file": "/tmp/issue-body.md" }
}
```

```json
{
  "body": { "$file": "/tmp/issue-body.md", "maxBytes": 2000000 }
}
```

--------------------------------

### Validate and preview tool calls

Source: https://context7.com/edimuj/callmux/llms.txt

Use `callmux_dry_run` to validate and preview tool calls without executing them. It returns the resolved call plan, cache-hit candidates, and any validation errors.

```json
{
  "calls": [
    { "server": "github", "tool": "create_issue", "arguments": { "title": "Test", "body": "Body" } },
    { "server": "github", "tool": "get_issue", "arguments": { "issue_number": 42 } }
  ]
}
```

--------------------------------

### Inline Mode for Remote Server

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Launch CallMux in inline mode to connect to a single remote MCP server, specifying the URL and necessary headers.

```bash
npx -y callmux --url https://mcp.example.com/mcp --header "Authorization:Bearer sk-..."
```

--------------------------------

### Define a Parallel Recipe for Concurrent Fetches

Source: https://github.com/edimuj/callmux/blob/main/docs/recipes.md

This recipe defines two concurrent calls to fetch issues for comparison. The results from both calls are returned together.

```json
{
  "recipes": {
    "triage_pair": {
      "description": "Fetch two issues for comparison",
      "mode": "parallel",
      "calls": [
        { "server": "github", "tool": "get_issue", "arguments": { "issue_number": { "$param": "first" } } },
        { "server": "github", "tool": "get_issue", "arguments": { "issue_number": { "$param": "second" } } }
      ]
    }
  }
}
```

--------------------------------

### Define a Batch Recipe for Bulk Operations

Source: https://github.com/edimuj/callmux/blob/main/docs/recipes.md

This recipe defines a batch operation to update multiple issues by adding the 'bug' label. It specifies the tool and provides a list of items, each with arguments for the issue number and labels.

```json
{
  "recipes": {
    "label_bugs": {
      "description": "Add bug label to multiple issues",
      "mode": "batch",
      "server": "github",
      "tool": "update_issue",
      "items": [
        { "arguments": { "issue_number": { "$param": "issue1" }, "labels": ["bug"] } },
        { "arguments": { "issue_number": { "$param": "issue2" }, "labels": ["bug"] } }
      ]
    }
  }
}
```

--------------------------------

### Configure Abuse Controls

Source: https://github.com/edimuj/callmux/blob/main/docs/enterprise.md

Set global and per-principal request limits and maximum concurrent requests to protect shared infrastructure. Configure an IP allowlist to restrict access.

```json
{
  "abuseControls": {
    "globalRequestsPerMinute": 1200,
    "principalRequestsPerMinute": 240,
    "principalMaxInFlight": 20,
    "cidrAllowlist": ["127.0.0.1/32", "::1/128"]
  }
}
```

--------------------------------

### Configure Callmux Client (Codex TOML)

Source: https://context7.com/edimuj/callmux/llms.txt

Configure Codex to connect to a callmux listener via streamable HTTP or a stdio bridge. The stdio bridge is recommended for enhanced features.

```toml
# Codex (~/.codex/config.toml) — streamable HTTP
[mcp_servers.callmux]
url = "http://localhost:4860/mcp"

# Codex with stdio bridge (recommended — adds cwd injection + resilient reconnect)
[mcp_servers.callmux]
command = "callmux"
args = ["bridge", "--url", "http://localhost:4860/mcp"]
```

--------------------------------

### Attach Callmux Client

Source: https://github.com/edimuj/callmux/blob/main/docs/cli-reference.md

Attach Callmux to a client configuration. Options include automatically confirming with '--yes', specifying a remote server URL, or using a stdio bridge.

```bash
callmux client attach claude --yes
```

```bash
callmux client attach codex --url http://localhost:4860/mcp --yes
```

```bash
callmux client attach codex --url http://localhost:4860/mcp --bridge --yes
```

--------------------------------

### Config Hot-Reload

Source: https://github.com/edimuj/callmux/blob/main/docs/shared-server.md

Callmux supports automatic hot-reloading of configuration files and manual triggering via SIGHUP.

```APIDOC
## Config Hot-Reload

In shared listener mode launched from a config file, callmux watches the config file and hot-reloads changes automatically. You can also trigger the same reload path with `SIGHUP`:

```bash
kill -HUP <callmux-pid>
```

callmux validates and connects the new upstream set before swapping it into the live listener. If parsing, validation, or upstream startup fails, the old runtime stays active and `callmux_status` reports the latest reload error under `listener.configReload`.

**Reloads** (no restart needed):
- `servers`, tool wiring, cache settings, recipes, `metaOnly`, `maxConcurrency`
- `auth`, `authorization`, `abuseControls`, `auditLog`, `metrics`
- `requestBodyMaxBytes`, `allowRequestBodyMaxOverride`, `allowInsecureRemoteListener`
- `responseShield`, `dashboard`

In-flight requests continue on the runtime they started with. New requests use the reloaded runtime after the swap, and stored `callmux_get_result` refs remain available across successful reloads until evicted.
```

--------------------------------

### Abuse Controls and Audit Logging Configuration

Source: https://context7.com/edimuj/callmux/llms.txt

Configure rate limiting (global and per-principal) and connection limits to prevent abuse. Enable audit logging with options to include request bodies and redact sensitive keys.

```json
{
  "abuseControls": {
    "globalRequestsPerMinute": 1200,
    "principalRequestsPerMinute": 240,
    "principalMaxInFlight": 20,
    "cidrAllowlist": ["10.0.0.0/8", "127.0.0.1/32"]
  },
  "auditLog": {
    "enabled": true,
    "includeRequestBody": false,
    "maxPayloadChars": 4096,
    "redactKeys": ["password", "secret", "token"]
  },
  "metrics": {
    "enabled": true,
    "path": "/metrics",
    "allowUnauthenticated": false
  }
}
```

--------------------------------

### Search available downstream tools

Source: https://context7.com/edimuj/callmux/llms.txt

Use `callmux_search_tools` to find available tools based on task description, keywords, server, or input field names. This is useful in meta-only mode for discovering tools without listing all definitions.

```json
{
  "query": "create github issue with labels",
  "limit": 5
}
```

--------------------------------

### Configure Callmux for Claude Code

Source: https://github.com/edimuj/callmux/blob/main/README.md

Add callmux configuration to your .mcp.json file to enable GitHub tools and callmux meta-tools for Claude.

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "callmux", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

--------------------------------

### Validate Configuration and Connectivity

Source: https://github.com/edimuj/callmux/blob/main/docs/cli-reference.md

Run the 'doctor' command to validate your Callmux configuration and test connectivity to all configured servers.

```bash
callmux doctor
```

--------------------------------

### Enable Dashboard in Callmux Config

Source: https://github.com/edimuj/callmux/blob/main/docs/dashboard.md

Add the 'dashboard' section to your callmux configuration file to enable the dashboard. Specify 'enabled' as true, set the desired 'path', and optionally configure 'maxEvents' for in-memory history.

```json
{
  "dashboard": {
    "enabled": true,
    "path": "/dashboard",
    "maxEvents": 500
  }
}
```

--------------------------------

### Configure Role-Based Access Control (RBAC)

Source: https://github.com/edimuj/callmux/blob/main/docs/enterprise.md

Define authorization rules for controlling access to tools based on principals and tool patterns. Set a default effect (allow or deny) for unmatched requests.

```json
{
  "authorization": {
    "defaultEffect": "deny",
    "rules": [
      {
        "id": "ops-all",
        "effect": "allow",
        "principals": ["bearer:ops"],
        "tools": ["*"]
      },
      {
        "id": "agents-read",
        "effect": "allow",
        "principals": ["oidc:*", "scope:mcp.read"],
        "tools": ["github__get_*", "github__list_*"]
      }
    ]
  }
}
```

--------------------------------

### Check Dashboard Data and Events Endpoints

Source: https://github.com/edimuj/callmux/blob/main/docs/dashboard.md

If the dashboard UI fails to connect, use curl to directly check the '/dashboard/data' and '/dashboard/events' endpoints. Ensure they return '200' and 'Content-Type: text/event-stream' respectively.

```bash
curl -i http://localhost:4860/dashboard/data
```

```bash
curl -i http://localhost:4860/dashboard/events
```

--------------------------------

### Tool Filtering with Meta-Only Mode

Source: https://github.com/edimuj/callmux/blob/main/docs/meta-only-mode.md

Explains how per-server tool whitelists interact with Meta-Only Mode.

```APIDOC
## Tool Filtering + Meta-Only

Per-server `tools: [...]` whitelists still apply. They filter what `callmux_call` can invoke and what `callmux_status` reports. This lets you hide tools even from discovery.
```