aufrank/using-mcp-tools-with-mcpc

mcpc: MCP command-line client

Use mcpc to interact with MCP (Model Context Protocol) servers from the command line. This is more efficient than function calling - generate shell commands instead.

Trust pattern

• Always: Read-only mcpc commands in the sandbox (e.g., tools-list, tools-get, resources-list/read, prompts-list/get, tools-call for read/search-only endpoints), session status checks, and commands that reuse already-created auth profiles.
• Ask: Anything that writes or needs network/OAuth (login/logout must be human-initiated in the foreground), connecting to new servers, commands that create/update/delete data, helper scripts that write files, or when sandbox blocks the command.
• Never: Destructive workspace actions (moves/deletes) without explicit user request; connecting to unknown MCP servers without instruction; backgrounding mcpc <server> login or trying to auto-open a browser.

Quick reference

# List sessions and auth profiles
mcpc

# Show server info
mcpc <server>
mcpc @<session>

# Tools
mcpc <target> tools-list
mcpc <target> tools-get <tool-name>
mcpc <target> tools-call <tool-name> key:=value key2:="string value"

# Resources
mcpc <target> resources-list
mcpc <target> resources-read <uri>

# Prompts
mcpc <target> prompts-list
mcpc <target> prompts-get <prompt-name> arg1:=value1

# Sessions (persistent connections)
mcpc <server> connect @<name>
mcpc @<name> <command>
mcpc @<name> close

# Authentication
mcpc <server> login
mcpc <server> logout

Target types

• mcp.example.com - Direct HTTPS connection to remote server
• localhost:8080 or 127.0.0.1:8080 - Local HTTP server (http:// is default for localhost)
• @session-name - Named persistent session (faster, maintains state)
• config-entry - Entry from config file (with --config)

Passing arguments

Prefer key:=value bindings. Use inline JSON only when needed (e.g., first-arg object or complex arrays):

# String values
mcpc @s tools-call search query:="hello world"

# Numbers, booleans, null (auto-parsed as JSON)
mcpc @s tools-call search query:="hello" limit:=10 enabled:=true

# Complex JSON values
mcpc @s tools-call search config:='{"nested":"value"}' items:='[1,2,3]'

# Force string type with JSON quotes
mcpc @s tools-call search id:='"123"'

# Inline JSON object (if first arg starts with { or [)
mcpc @s tools-call search '{"query":"hello","limit":10}'

# From stdin (auto-detected when piped)
echo '{"query":"hello"}' | mcpc @s tools-call search

JSON output for scripting

Always use --json flag for machine-readable output:

# Get tools as JSON
mcpc --json @apify tools-list

# Call tool and parse result with jq
mcpc --json @apify tools-call search query:="test" | jq '.content[0].text'

# Chain commands
mcpc --json @server1 tools-call get-data | mcpc @server2 tools-call process

Sessions for efficiency

Create sessions for repeated interactions:

# Create session (or reconnect if exists)
mcpc mcp.apify.com connect @apify

# Use session (faster - no reconnection overhead)
mcpc @apify tools-list
mcpc @apify tools-call search query:="test"

# Restart session (useful after server updates)
mcpc @apify restart

# Close when done
mcpc @apify close

Session states:

• 🟢 live - Bridge running, server might or might not be responding
• 🟡 crashed - Bridge crashed; auto-restarts on next use
• 🔴 expired - Server rejected session; needs close and reconnect

Authentication

OAuth (interactive login – human-only, foreground):

• mcpc <server> login opens the browser; mcpc never opens it itself. Do not background this command or it will miss the localhost callback.
• Run login once per profile, then reuse the saved credentials in scripts.
• Re-run login to refresh/change scopes.

Python preflight to enforce “login first” in scripts (no automatic browser launches):

import json, os, sys

server = os.environ.get("MCP_SERVER", "mcp.apify.com")
profile = os.environ.get("MCP_PROFILE", "default")
profiles_path = os.path.join(os.path.expanduser("~"), ".mcpc", "profiles.json")

try:
    data = json.load(open(profiles_path, "r", encoding="utf-8"))
    profiles = data.get("profiles", [])
except FileNotFoundError:
    profiles = []

has_profile = any(p.get("server") == server and p.get("name") == profile for p in profiles)
if not has_profile:
    print(f"No mcpc auth profile '{profile}' for {server}.")
    print(f"Run this yourself (foreground): mcpc {server} login --profile {profile}")
    sys.exit(1)

After the preflight succeeds, scripts may call mcpc --profile <name> ... or rely on the default profile.

Bearer token:

mcpc -H "Authorization: Bearer $TOKEN" mcp.apify.com tools-list
mcpc -H "Authorization: Bearer $TOKEN" mcp.apify.com connect @myserver

Proxy server for AI isolation

Create a proxy MCP server that hides authentication tokens:

# Human creates authenticated session with proxy
mcpc mcp.apify.com connect @ai-proxy --proxy 8080

# AI agent connects to proxy (no access to original tokens)
# Note: localhost defaults to http://
mcpc localhost:8080 tools-list
mcpc 127.0.0.1:8080 connect @sandboxed

Common patterns

List and inspect tools:

mcpc @s tools-list
mcpc @s tools-get tool-name

Call tool and extract text result:

mcpc --json @s tools-call my-tool | jq -r '.content[0].text'

Read resource content:

mcpc @s resources-read "file:///path/to/file"

Use config file for local servers:

mcpc --config .vscode/mcp.json filesystem resources-list

Exit codes

• 0 - Success
• 1 - Client error (invalid arguments)
• 2 - Server error (tool failed)
• 3 - Network error
• 4 - Authentication error

Debugging

# Verbose output shows protocol details
mcpc --verbose @s tools-call my-tool

Example script

See docs/examples/company-lookup.sh for a complete example of an AI-generated script that validates prerequisites and calls MCP tools.