MCPInstall

mcpc-mcp-client

by reason-machinesAI & Agents

Universal CLI client for Model Context Protocol (MCP) with persistent sessions, OAuth, tasks, and JSON output for shell scripting

Installs
189
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/mcp-skills --skill mcpc-mcp-client
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads mcpc-mcp-client automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

mcpc MCP Client Skill

Skill by ara.so — MCP Skills collection.

Overview

mcpc is a universal command-line client for the Model Context Protocol (MCP) that maps MCP operations to intuitive shell commands. It enables interactive debugging, scripting workflows, and AI agent integration with MCP servers through persistent sessions, OAuth 2.1 authentication, and JSON output mode.

Key capabilities:

  • Persistent sessions: Keep multiple stateful MCP connections alive simultaneously
  • Full MCP support: Tools, resources, prompts, async tasks, instructions
  • OAuth 2.1: Secure authentication with OS keychain credential storage
  • Code mode: JSON output for shell pipelines (jq, xargs, scripting)
  • Progressive discovery: Search tools across sessions to save tokens
  • MCP proxy: Share sessions across agents while protecting credentials

Installation

# Install globally via npm
npm install -g @apify/mcpc

# Or with Bun
bun install -g @apify/mcpc

# Verify installation
mcpc --version

Linux headless setup (if keychain is needed):

# Install dependencies
sudo apt-get install libsecret-1-0 gnome-keyring

# Run with keychain
dbus-run-session -- bash -c "echo -n 'password' | gnome-keyring-daemon --unlock && mcpc ..."

Core Commands

Session Management

# List all active sessions and OAuth profiles
mcpc
mcpc --json  # JSON output for scripting

# Connect to remote MCP server (HTTPS)
mcpc connect mcp.apify.com @apify
mcpc connect https://mcp.example.com @example

# Connect to local MCP server via config file
mcpc connect ~/.vscode/mcp.json:filesystem @fs
mcpc connect ./mcp-config.json:my-server @local

# Show session info (capabilities, tools overview)
mcpc @apify

# Close a session
mcpc close @apify

# Restart session (loses state)
mcpc restart @apify

# Interactive shell
mcpc @apify shell

Authentication

# Login with OAuth and save profile
mcpc login mcp.apify.com
mcpc login mcp.apify.com --profile production

# Use saved profile when connecting
mcpc connect mcp.apify.com @apify --profile production

# Logout (delete OAuth profile)
mcpc logout mcp.apify.com
mcpc logout mcp.apify.com --profile production

Tool Discovery and Search

# Search tools and instructions across all sessions
mcpc grep "search"
mcpc grep "actor" --json

# Search within a single session
mcpc @apify grep "web scraping"

# Search with regex
mcpc grep "search|find" -E

# Case-sensitive search
mcpc grep "Search" --case-sensitive

# Limit results
mcpc grep "data" -m 10

# Search resources and prompts
mcpc grep "config" --resources --prompts

MCP Operations

Tools

// List all tools
mcpc @apify tools-list
mcpc --json @apify tools-list  // JSON output

// Get tool details and schema
mcpc @apify tools-get search-actors

// Call tool with key:=value arguments
mcpc @apify tools-call search-actors keywords:="web scraper"
mcpc @apify tools-call search-actors keywords:="web scraper" limit:=5

// Call with JSON object
mcpc @apify tools-call search-actors '{"keywords":"web scraper","limit":5}'

// Call with stdin
echo '{"keywords":"web scraper","limit":5}' | mcpc @apify tools-call search-actors
cat args.json | mcpc @apify tools-call search-actors

// Force string type with JSON quotes
mcpc @apify tools-call get-item id:='"123"' flag:='"true"'

// Complex nested arguments
mcpc @apify tools-call create-actor 'config:={"timeout":300,"memory":512}'

Argument parsing rules:

  • key:=value auto-parses: numbers, booleans, objects stay typed
  • Invalid JSON becomes a string: name:=hello → "hello"
  • Force string with quotes: id:='"123"' → "123" (string)
  • No spaces around :=
  • Quote shell expansions: "query:=${VAR}"

Resources

// List resources
mcpc @apify resources-list

// Read resource
mcpc @apify resources-read file:///path/to/resource

// Subscribe to resource updates
mcpc @apify resources-subscribe file:///config.json

// Unsubscribe
mcpc @apify resources-unsubscribe file:///config.json

// List resource templates
mcpc @apify resources-templates-list

Prompts

// List prompts
mcpc @apify prompts-list

// Get prompt with arguments
mcpc @apify prompts-get analyze-data dataset:="sales-2024"
mcpc @apify prompts-get analyze-data '{"dataset":"sales-2024","format":"csv"}'

// Pipe arguments
echo '{"dataset":"sales-2024"}' | mcpc @apify prompts-get analyze-data

Async Tasks

// List tasks
mcpc @apify tasks-list

// Get task status
mcpc @apify tasks-get task-12345

// Get task result (waits for completion)
mcpc @apify tasks-result task-12345

// Cancel task
mcpc @apify tasks-cancel task-12345

Server Operations

// Ping server
mcpc @apify ping

// Set logging level
mcpc @apify logging-set-level debug
mcpc @apify logging-set-level info

Code Mode (JSON Output)

Use --json flag for shell scripting and pipelines:

# Get session list as JSON
mcpc --json | jq '.sessions[] | select(.status == "connected")'

# Extract tool names
mcpc --json @apify tools-list | jq -r '.tools[].name'

# Filter tools by category
mcpc --json @apify tools-list | jq '.tools[] | select(.description | contains("search"))'

# Call tool and parse result
RESULT=$(mcpc --json @apify tools-call search-actors keywords:="crawler")
echo "$RESULT" | jq '.content[0].text'

# Chain multiple operations
mcpc --json @apify tools-list | \
  jq -r '.tools[].name' | \
  xargs -I {} mcpc --json @apify tools-get {}

# Batch process with jq + xargs
echo '["actor1","actor2","actor3"]' | \
  jq -r '.[]' | \
  xargs -I {} mcpc --json @apify tools-call get-actor actorId:="{}"

Configuration

MCP Config File Format

Reference local MCP servers via config files (Claude Desktop format):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "postgres": {
      "command": "node",
      "args": ["/path/to/postgres-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Connect to entries:

mcpc connect ~/.vscode/mcp.json:filesystem @fs
mcpc connect ./config.json:postgres @db

Environment Variables

# Use in MCP config files
export DATABASE_URL="postgresql://user:pass@localhost/db"
export API_KEY="your-api-key"

# mcpc options via env
export MCPC_TIMEOUT=600
export MCPC_MAX_CHARS=10000

Global Options

# Request timeout
mcpc @apify tools-call long-task --timeout 600

# Truncate output
mcpc @apify tools-call verbose-tool --max-chars 5000

# Skip TLS verification (self-signed certs)
mcpc connect https://localhost:3000 @local --insecure

# Debug logging
mcpc --verbose @apify tools-call search-actors keywords:="test"

# Use specific OAuth profile
mcpc connect mcp.apify.com @apify --profile staging

AI Agent Integration

Bash Tool Pattern

Give agents a single Bash() tool with mcpc in scope:

// Agent tool definition
const bashTool = {
  name: "bash",
  description: "Execute bash commands. mcpc is available for MCP operations.",
  parameters: {
    command: { type: "string", description: "Bash command to execute" }
  }
};

// Agent can now use MCP naturally
await bash("mcpc connect mcp.apify.com @apify");
await bash("mcpc @apify grep 'web scraping'");
await bash("mcpc --json @apify tools-call search-actors keywords:='crawler' | jq -r '.content[0].text'");

Shared Sessions

Multiple agents can share the same mcpc sessions:

# Agent 1: Create session
mcpc connect mcp.apify.com @shared

# Agent 2: Use same session
mcpc @shared tools-list

# Agent 3: Call tools
mcpc @shared tools-call search-actors keywords:="data"

MCP Proxy Mode

Protect credentials from AI-generated code:

# Start proxy in trusted environment
mcpc connect mcp.apify.com @apify
# Share session name with agent, not credentials

# Agent uses proxy without OAuth access
mcpc @apify tools-call search-actors keywords:="test"

Common Patterns

Discovery Workflow

# 1. Connect to server
mcpc connect mcp.apify.com @apify

# 2. Search for relevant tools
mcpc @apify grep "search"

# 3. Get tool details
mcpc @apify tools-get search-actors

# 4. Call tool
mcpc @apify tools-call search-actors keywords:="web crawler"

Scripting Workflow

#!/bin/bash
set -e

# Connect if not already connected
mcpc connect mcp.apify.com @apify 2>/dev/null || true

# Search for actors
ACTORS=$(mcpc --json @apify tools-call search-actors keywords:="crawler")

# Extract actor IDs
echo "$ACTORS" | jq -r '.content[0].text | fromjson | .items[].id' | while read -r ID; do
  # Get details for each actor
  mcpc --json @apify tools-call get-actor actorId:="$ID"
done

Multi-Server Orchestration

# Connect to multiple servers
mcpc connect mcp.apify.com @apify
mcpc connect ~/.vscode/mcp.json:filesystem @fs
mcpc connect ./config.json:database @db

# Search across all
mcpc grep "search" --json | jq -r '.results[] | "\(.session): \(.item.name)"'

# Coordinate operations
DATA=$(mcpc --json @fs tools-call read-file path:="/data/input.json")
RESULT=$(echo "$DATA" | mcpc @apify tools-call process-data)
echo "$RESULT" | mcpc @db tools-call store-result

Progressive Tool Discovery

# Start broad, refine as needed
mcpc grep "actor" --json | jq -r '.results[].item.name' | head -3

# Get details only for relevant tools
mcpc @apify tools-get search-actors

# Call with minimal context
mcpc @apify tools-call search-actors keywords:="web scraping"

Troubleshooting

Session Issues

# Check session status
mcpc
mcpc --json | jq '.sessions[] | {name, status}'

# Restart crashed session
mcpc restart @apify

# Clean stale sessions
mcpc clean sessions

# Debug connection
mcpc --verbose connect mcp.apify.com @apify

Authentication Issues

# Re-authenticate
mcpc logout mcp.apify.com
mcpc login mcp.apify.com

# Use different profile
mcpc login mcp.apify.com --profile staging
mcpc connect mcp.apify.com @apify --profile staging

# Check saved profiles
mcpc --json | jq '.profiles'

# Linux: verify keychain
secret-tool search service mcpc

# Clean credentials
mcpc clean profiles

Tool Call Issues

# Get tool schema first
mcpc @apify tools-get search-actors

# Validate arguments
echo '{"keywords":"test"}' | jq .  # Validate JSON

# Debug with verbose
mcpc --verbose @apify tools-call search-actors keywords:="test"

# Check argument parsing
mcpc @apify tools-call test-tool \
  string:="hello" \
  number:=42 \
  bool:=true \
  obj:='{"key":"value"}' \
  arr:='[1,2,3]'

Timeout Issues

# Increase timeout
mcpc @apify tools-call long-task --timeout 600

# For async tasks, use tasks-result
TASK_ID=$(mcpc --json @apify tools-call start-task | jq -r '.taskId')
mcpc @apify tasks-result "$TASK_ID"  # Waits for completion

Credentials on Linux

# If keychain fails, mcpc falls back to ~/.mcpc/credentials

# Force keychain with gnome-keyring
dbus-run-session -- bash -c "
  echo -n 'password' | gnome-keyring-daemon --unlock
  mcpc login mcp.apify.com
"

# Check file-based credentials (mode 0600)
ls -la ~/.mcpc/credentials

Clean Up

# Clean specific resources
mcpc clean sessions    # Close all sessions
mcpc clean profiles    # Delete OAuth profiles
mcpc clean logs        # Remove old log files
mcpc clean all         # Everything

# Manual cleanup
rm -rf ~/.mcpc/sessions/*
rm -rf ~/.mcpc/logs/*

Advanced Usage

Custom Timeout and Limits

# Per-command timeout
mcpc @apify tools-call slow-operation --timeout 900

# Truncate verbose output
mcpc @apify tools-call get-logs --max-chars 10000

# Combine options
mcpc --json --verbose --timeout 600 @apify tools-call complex-task

Resource Subscriptions

# Subscribe to config changes
mcpc @apify resources-subscribe config://app-settings

# Monitor in background, process updates
mcpc @apify resources-subscribe config://app-settings &
# Updates arrive asynchronously

# Unsubscribe when done
mcpc @apify resources-unsubscribe config://app-settings

Interactive Shell Commands

mcpc @apify shell

# Inside shell:
# > help
# > tools-list
# > tools-call search-actors keywords:="crawler"
# > exit

Use arrow keys for history, Ctrl+C to cancel, Ctrl+D or exit to quit.

Security Notes

  • OAuth tokens stored in OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
  • Fallback to ~/.mcpc/credentials (mode 0600) on headless Linux
  • Use --insecure only for self-signed certs in dev environments
  • Environment variables in config files: "${VAR_NAME}"
  • Never commit credentials or ~/.mcpc/credentials to version control

FAQ

What does the mcpc-mcp-client skill do?

Universal CLI client for Model Context Protocol (MCP) with persistent sessions, OAuth, tasks, and JSON output for shell scripting

How do I install mcpc-mcp-client?

Run npx skills add https://github.com/reason-machines/mcp-skills --skill mcpc-mcp-client in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mcpc-mcp-client/ (personal) or .claude/skills/mcpc-mcp-client/ (project).

Which AI agents can use mcpc-mcp-client?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is mcpc-mcp-client safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains mcpc-mcp-client?

It is published by reason-machines in reason-machines/mcp-skills. It has 189 recorded installs.

More from reason-machines/mcp-skills

View all →

codebase-memory-mcp-intelligence

reason-machines/mcp-skills

High-performance code intelligence MCP server that indexes codebases into knowledge graphs for structural queries, call traces, and architecture analysis

AI & Agents505 installs

playwright-mcp-server

reason-machines/mcp-skills

Browser automation MCP server using Playwright's accessibility tree for LLM-friendly web interaction

AI & Agents285 installs

tradingview-mcp-assistant

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents256 installs

lanhu-mcp-collaboration

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents245 installs

chrome-devtools-mcp-automation

reason-machines/mcp-skills

Expert guidance for Chrome DevTools MCP server - browser automation, debugging, and performance analysis for AI agents

AI & Agents239 installs

github-mcp-server

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents237 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs