Skip to main content

CLI

The mcpbundles CLI gives you full MCP access from the terminal — tool discovery, search, execution, and an interactive shell.

Installation​

On Mac and PC, install MCPBundles Desktop from the download page. Desktop supervises the CLI sidecar and puts mcpbundles on your PATH — you do not need a separate pip install for normal terminal use on that machine.

Headless: pip or pipx (CI, Linux, servers)​

When Desktop is not installed (Linux servers, CI, scripts only):

pip install mcpbundles
Use pipx on a developer laptop without Desktop

For a cleaner installation that doesn't affect your global Python environment:

pipx install mcpbundles

Requires Python 3.10+. Check the installed version:

mcpbundles --version

Authentication​

Three ways to authenticate, in order of precedence:

Named connections store credentials encrypted on disk. Best for multi-environment setups.

mcpbundles connect prod --url https://mcp.mcpbundles.com --default

The CLI prompts for your API key interactively. Create or copy a workspace API key under Settings → API Keys (/w/{workspace}/settings/security). See Using API Keys for headers, rotation, and MCP URL rules.

2. Environment Variable​

For CI/CD or ephemeral usage:

export MCPBUNDLES_API_KEY=mb_your_key_here
mcpbundles tools

3. Browser OAuth​

mcpbundles login

Opens your browser for the OAuth flow. Tokens are stored locally and refreshed automatically.

Auth Precedence​

When using a named connection (--as name), auth resolves in this order:

  1. Connection stored auth — API key or OAuth token set during mcpbundles connect
  2. MCPBUNDLES_API_KEY env var
  3. Global OAuth token — from mcpbundles login

Named Connections​

Manage multiple environments (dev, staging, prod) or multiple workspaces.

# Create connections
mcpbundles connect prod --url https://mcp.mcpbundles.com --default
mcpbundles connect staging --url https://mcp.mcpbundles.com --oauth

# List all connections
mcpbundles connections

# Use a specific connection
mcpbundles tools --as staging

# Set a different default
mcpbundles connect prod --default

# Remove a connection
mcpbundles disconnect staging
Progressive Disclosure

If you only have one connection, it's auto-selected — no --as flag needed. The --as flag only becomes necessary when you have multiple connections without a default.

Use mcpbundles use <name> only when you want to change the default connection for every following command in that shell. For a one-off call against another environment, prefer --as <name> on that command instead of use — switching default away from production is easy to forget.

Discovering Tools​

Hub Tools​

List platform-level tools (MCP servers, search, agents, health):

mcpbundles tools --as prod

MCP Server Tools​

List tools within a specific MCP server:

mcpbundles tools --server attio --as prod

Filter by keyword:

mcpbundles tools --server hubspot-crm --filter "contact"

Tool Detail​

Get the full schema and description for a specific tool:

mcpbundles tools attio-list-lists-5b7 --server attio

Find MCP Servers​

Search for MCP servers by name, category, or description:

mcpbundles call discover_mcp_servers -- search="email campaign"

Returns server results with slugs, connection options, tool counts, and workspace status. After choosing a server, list its tools with mcpbundles tools --server <slug>.

JSON Output​

Add --json for machine-readable output:

mcpbundles tools --server attio --json | jq '.[] | .name'

Calling Tools​

Hub Tools​

Hub tools don't need a --server flag:

mcpbundles call health_check
mcpbundles call list_connected_mcp_servers
mcpbundles call discover_mcp_servers search="CRM contacts"
mcpbundles call list_tool_executions limit:=5

MCP Server Tools​

Use --server to call tools directly on an MCP server endpoint:

mcpbundles call attio-list-lists-5b7 --server attio
mcpbundles call attio-list-objects-5b7 --server attio --as prod -- limit:=25

When you pass --server, put -- before key=value tool arguments so the CLI does not confuse them with its own flags:

mcpbundles call attio-list-lists-5b7 --server attio -- limit:=10

Argument Formats​

# Key=value strings (auto-coerces booleans and numbers)
mcpbundles call tool_name key=value active=true count=10

# Typed JSON values with :=
mcpbundles call tool_name limit:=25 tags:='["a","b"]'

# Full JSON object
mcpbundles call tool_name '{"key": "value", "count": 42}'

Output Modes​

# Default: parsed JSON
mcpbundles call health_check

# Pretty: Rich syntax highlighting
mcpbundles call health_check --pretty

# Raw: full MCP response envelope
mcpbundles call health_check --raw

Code Execution​

The exec command runs Python code in the Hub's sandbox with access to all enabled MCP server tools:

# Inline
mcpbundles exec "result = await health_check(); print(result)"

# Multi-step workflow
mcpbundles exec "
tools = await list_tools('attio')
for t in tools[:5]:
    print(t['function_name'])
"

# Call MCP server tools (requires server= parameter inside sandbox)
mcpbundles exec "
result = await attio_list_lists_5b7(server='attio')
for l in result['data']:
    print(l['name'])
"

# From file
mcpbundles exec -f script.py

# Streaming output
mcpbundles exec --stream "print('streaming line by line')"

# From stdin
echo "print('hello')" | mcpbundles exec --stdin
Tool names have hash suffixes

Never guess tool names. Discover them first:

mcpbundles exec "tools = await list_tools('attio'); print([t['function_name'] for t in tools])"

Resources and Prompts​

# List resources
mcpbundles resources
mcpbundles resources --server browser

# Read a resource
mcpbundles read "ui://mcpbundles/app"

# List prompts
mcpbundles prompts
mcpbundles prompts --server attio

Interactive Shell​

Start a REPL with tab completion and live connection switching:

mcpbundles shell --as prod

Shell commands:

CommandAction
toolsList available tools
tools <name>Show tool detail
call <tool> k=vExecute a tool
exec "code"Run code_execution
use <name>Switch to a different connection
helpShow all commands
exitClose the shell

Agent Integration​

Agent skill files​

Generate the MCPBundles CLI skill for coding agents (discovery and call patterns):

mcpbundles init --as mcpbundles_prod

This writes .skills/mcpbundles-cli/ — not a JSON tool manifest and not host MCP config.

Local MCP Proxy​

Start a local MCP server that aggregates multiple upstream connections:

mcpbundles serve --as prod --port 8080

Desktop Proxy​

Connect local services (PostgreSQL, browsers, SQLite) to the MCPBundles platform via a secure WebSocket tunnel.

mcpbundles proxy start
mcpbundles proxy status
mcpbundles proxy logs -f
mcpbundles proxy stop

See the Desktop Connection guide for full setup instructions.

MCP Connect Auth smoke tests​

If you publish an MCP server with MCP Connect Auth, run the same probe ladder as maintainer Connect Readiness:

mcpbundles connect doctor --listing your-slug --env staging --surface bundle
mcpbundles connect doctor --listing your-slug --surface origin --base-url https://mcp.example.com

See MCP Connect Auth for flags, JSON output, and federation probes.

Configuration​

mcpbundles config show     # show all settings
mcpbundles config set k v  # set a value
mcpbundles config get k    # get a value
mcpbundles config reset    # reset to defaults

Error Handling​

The CLI uses differentiated exit codes:

Exit CodeMeaningExample
0SuccessTool returned a result
1User errorBad connection name, no auth
2Tool errorUnknown tool, tool execution failure
3Connection errorServer unreachable
4Internal errorUnexpected failure

Error messages are actionable — they tell you what to try next.

Troubleshooting​

ProblemSolution
Unknown tool: XTool name is wrong or missing hash suffix. Run mcpbundles tools --server <slug> to find the exact name.
Connection 'X' not foundThe connection doesn't exist. Run mcpbundles connections to list available connections, then mcpbundles connect X to create it.
Authentication failed (401)Credentials expired or invalid. Re-run mcpbundles connect <name> to store fresh credentials.
Cannot connect to ...Server is down or URL is wrong. Run mcpbundles connections to see the configured URL.
Empty results from MCP server callWrong server slug. Run mcpbundles call list_connected_mcp_servers to list available MCP servers.
Multiple connections exist but none is defaultRun mcpbundles connect <name> --default to set a default, or use --as <name> explicitly.

Quick Reference​

# Setup (Desktop installs mcpbundles on PATH; otherwise pip/pipx install mcpbundles)
mcpbundles connect prod --url https://mcp.mcpbundles.com --default

# Discover
mcpbundles tools                                    # hub tools
mcpbundles call list_connected_mcp_servers          # connected MCP servers
mcpbundles call discover_mcp_servers -- search="email" # catalog search
mcpbundles tools --server attio                     # MCP server tools
mcpbundles tools --server attio --filter "webhook"  # filtered

# Execute
mcpbundles call health_check                        # hub tool
mcpbundles call attio-list-lists-5b7 --server attio -- limit:=10 # MCP server tool
mcpbundles exec "print(await health_check())"       # code execution

# Manage
mcpbundles connections                              # list connections
mcpbundles shell                                    # interactive REPL
mcpbundles proxy start                              # desktop tunnel