Ask AI:

PerplexityClaudeChatGPTGoogleGrok

CLI

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

Installation

pip install mcpbundles

Recommended: Use pipx

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:

1. Named Connections (Recommended)

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. You can find your API key at mcpbundles.com under Settings → API Keys.

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

# 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.

---

Discovering Tools

Hub Tools

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

mcpbundles tools --as prod

Bundle Tools

List tools within a specific bundle:

mcpbundles tools --bundle attio --as prod

Filter by keyword:

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

Tool Detail

Get the full schema and description for a specific tool:

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

Search

Search across all enabled tools by keyword:

mcpbundles call search_tools query="email campaign"

Returns ranked results with tool name, bundle, provider, score, and a usage example.

JSON Output

Add --json for machine-readable output:

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

---

Calling Tools

Hub Tools

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

mcpbundles call health_check
mcpbundles call get_bundles
mcpbundles call search_tools query="CRM contacts"
mcpbundles call get_executions limit:=5

Bundle Tools

Use --bundle to call tools directly on a bundle endpoint:

mcpbundles call attio-list-lists-5b7 --bundle attio
mcpbundles call attio-list-objects-5b7 --bundle attio --as prod

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 bundle 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 bundle tools (requires bundle= parameter inside sandbox)
mcpbundles exec "
result = await attio_list_lists_5b7(bundle='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 --bundle browser

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

# List prompts
mcpbundles prompts
mcpbundles prompts --bundle attio

---

Interactive Shell

Start a REPL with tab completion and live connection switching:

mcpbundles shell --as prod

Shell commands:

Command	Action
tools	List available tools
tools <name>	Show tool detail
call <tool> k=v	Execute a tool
exec "code"	Run code_execution
use <name>	Switch to a different connection
help	Show all commands
exit	Close the shell

---

Agent Integration

Tool Manifest

Generate a static snapshot of available tools for agent configuration:

mcpbundles init --as prod -o tools.json

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.

---

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 Code	Meaning	Example
0	Success	Tool returned a result
1	User error	Bad connection name, no auth
2	Tool error	Unknown tool, tool execution failure
3	Connection error	Server unreachable
4	Internal error	Unexpected failure

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

---

Troubleshooting

Problem	Solution
Unknown tool: X	Tool name is wrong or missing hash suffix. Run mcpbundles tools --bundle <slug> to find the exact name.
Connection 'X' not found	The 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 bundle call	Wrong bundle slug. Run mcpbundles call get_bundles to list available bundles.
Multiple connections exist but none is default	Run mcpbundles connect <name> --default to set a default, or use --as <name> explicitly.

---

Quick Reference

# Setup
pip install mcpbundles
mcpbundles connect prod --url https://mcp.mcpbundles.com --default

# Discover
mcpbundles tools                                    # hub tools
mcpbundles tools --bundle attio                     # bundle tools
mcpbundles tools --bundle attio --filter "webhook"  # filtered
mcpbundles call search_tools query="email"          # search

# Execute
mcpbundles call health_check                        # hub tool
mcpbundles call attio-list-lists-5b7 --bundle attio # bundle tool
mcpbundles exec "print(await health_check())"       # code execution

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