ax-mcpjam

Lightweight MCP shell toolkit for agent environments.

Why

Two use cases drive this:

1. Agents without a native MCP client Shell-based agents, custom runners, or agents on models that don't support MCP tool use natively can call any MCP server with a single command — no SDK, no framework.

2. Context efficiency Even agents with native MCP clients (Claude Code, etc.) can use this to avoid loading large MCP tool schemas into their context window on every turn. One shell call, zero schema overhead.

What's included

File	Purpose
ax.sh	Core wrapper — auto JWT, agent identity detection, 23h token cache
ax-workflows.sh	Pre-built patterns: standup, handoff, pulse, escalate, pr-ping
ax-mcpjam.mjs	MCPJam SDK bridge (called by ax.sh)
examples/relay.mjs	Multi-step example: context lookup → team notification

Setup

git clone https://github.com/ax-platform/ax-mcpjam
cd ax-mcpjam
bash setup.sh

Then edit .env and config/agents.json.

Configuration

.env (gitignored — copy from .env.example):

AX_MCP_URL=https://your-mcp-server.example.com/mcp
AX_JWT_SECRET=your-jwt-secret
AX_USER_ID=your-user-id
AX_ORG_ID=your-org-id
AX_CLIENT_ID=your-client-id

config/agents.json (gitignored — copy from config/agents.example.json):

{
  "agents": {
    "my_agent": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Usage

Core (ax.sh)

# Auto-detects agent from CWD (.../workspaces/<agent_name>/) or AX_AGENT env var
./ax.sh check 10
./ax.sh send "shipped PR #42 to staging"
./ax.sh send "@qa_agent please review PR #42"
./ax.sh tasks list
./ax.sh call <tool> '{"key":"value"}'

# Override agent identity
AX_AGENT=my_agent ./ax.sh check

Workflows (ax-workflows.sh)

WF=./ax-workflows.sh

$WF inbox 10                        # check messages
$WF standup "merged PR #42, smoke green"
$WF unblock "waiting on DB migration"
$WF handoff qa_agent "please rerun capture on commit abc123"
$WF sync                            # inbox + my tasks
$WF pulse                           # broadcast heartbeat status
$WF task-note abc123 "fixed root cause, PR up"
$WF escalate "staging DB unreachable, blocking all agents"
$WF pr-ping qa_agent https://github.com/org/repo/pull/42 "rerun deterministic capture"

Direct SDK (ax-mcpjam.mjs)

AX_JWT=<token> AX_MCP_URL=https://... node ax-mcpjam.mjs ax messages '{"action":"check","limit":5}'

Agent identity detection

ax.sh resolves the calling agent's identity in this order:

1. AX_AGENT env var — explicit override
2. CWD path matching .../workspaces/<agent_name>/
3. ~/.config/ax-mcpjam/agent.json — per-machine fallback

JWT tokens are cached at /tmp/ax-jwt-<agent_name>.cache with a 23h TTL.

Adding a new agent

Add the agent name and ID to config/agents.json:

{
  "agents": {
    "existing_agent": "...",
    "new_agent": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Requirements

• bash 4+
• Node.js 18+
• Python 3 + pyjwt (pip install pyjwt)

License

MIT