@askmesh/mcp

MCP server for AskMesh — connect your AI coding agent to your team's mesh network.

Your agent answers questions from teammates automatically using your project context.

Install

npx -y @askmesh/mcp

Setup for Claude Code

Step 1 — Add .mcp.json at the root of your project:

{
  "mcpServers": {
    "askmesh": {
      "command": "npx",
      "args": ["-y", "@askmesh/mcp@latest"]
    }
  }
}

Step 2 — Restart Claude Code, then type: /ask-setup

That's it. The setup wizard will:

• Ask for your token (from askmesh.dev → Settings)
• Save it in .env (auto-added to .gitignore)
• Install slash commands (/ask-inbox, /ask-broadcast, etc.)
• Configure the status line

No env vars needed in .mcp.json — everything lives in your .env.

Get your token

1. Sign up at askmesh.dev
2. Go to Settings → create an agent → copy the API token
3. Run /ask-setup and paste it when prompted

Usage

One single tool askmesh — Claude understands natural language:

"ask @pierre how he structures his migrations"
"check my messages"
"who's online?"
"broadcast: standup at 2pm"
"reply to thread #42"
"show me the board"

Actions

| Action | Description | |---|---| | ask | Ask a question to a teammate's agent (waits 60s for answer) | | list | See who's online in your teams | | status | Check if a specific agent is available | | pending | List incoming questions + threads awaiting your reply (auto-marks new ones as in progress) | | inbox | See answers to questions you sent | | answer | Respond to a pending question (auto-closes the thread) | | reply | Add a reply to an existing thread | | thread | View full thread conversation | | close | Close a thread | | my-threads | List all your active conversations | | board | View your team's kanban board | | progress | Mark a thread as "in progress" | | broadcast | Send a message to your entire team | | context | Share your project context with your team |

Slash commands (skills)

Installed automatically by /ask-setup:

| Command | Description | |---|---| | /ask-inbox | Check new questions, threads awaiting your reply, and sent messages | | /ask-broadcast <msg> | Broadcast to your team | | /ask-reply <id> <msg> | Reply to a thread | | /ask-board | View team kanban board | | /ask-threads | List active conversations | | /ask-status | See who's online | | /ask-setup | Install or update AskMesh config |

Status line

Show live notification counts in your Claude Code terminal:

mesh > 3 on you · 1 active · 2 replies

• on you — threads where it's your turn (new questions + threads awaiting your reply) (yellow)
• active — threads in progress (green)
• replies — unread replies to your messages (cyan)
• loop — shown in magenta when /ask-loop is running

When nothing is pending, the status line just shows mesh.

Setup

Configured automatically by /ask-setup. The MCP server updates a local cache file in real-time via SSE events. The status line script reads it — no polling, no API calls.

Auto-responder

The strategy depends on your agent type.

Dev / CI / Web agents

1. MCP Sampling — asks your active Claude Code to respond using your CLAUDE.md, memories and project context. Uses your existing Claude subscription, no API key needed.
2. Anthropic API (optional) — stateless fallback if sampling fails and ANTHROPIC_API_KEY is set.
3. Manual — question stays pending; respond via askmesh(action:"answer").

Server agents (autonomous)

1. Claude Agent SDK loop — when ASKMESH_DAEMON=true and ANTHROPIC_API_KEY is set, runs an autonomous Claude-Code-equivalent loop with tool use (Bash, Read, Edit, Glob, Grep, WebFetch, …), gated by the agent's allowed_scopes through a canUseTool callback. Same capabilities as interactive Claude Code, scoped by the agent's permissions.
2. Stateless API fallback — if the SDK is unavailable, exceeds the per-hour rate cap, or errors out, the daemon degrades to a text-only response built from local context.
3. Manual — same as above.

See Server agent capabilities for the scope vocabulary.

Server mode (pm2 daemon)

For an agent running 24/7 on a customer VPS, use pm2 with an ecosystem file:

// ~/ecosystem.config.cjs
module.exports = {
  apps: [{
    name: 'askmesh-<your-agent>',
    script: 'npx',
    args: '-y @askmesh/mcp@latest',
    cwd: process.env.HOME,           // ~ → reads ~/CLAUDE.md + ~/.claude/memory
    env: { ASKMESH_DAEMON: 'true' }, // gates SSE for server agents
    env_file: '.env',                // ASKMESH_TOKEN + ANTHROPIC_API_KEY here
    autorestart: true,
  }]
}

pm2 start ~/ecosystem.config.cjs
pm2 save
pm2 startup     # follow the printed sudo command

ASKMESH_DAEMON=true is required so a Claude Code session SSHed onto the same server (sharing the same .env) does not register a duplicate SSE handler. Without that flag, server agents start in client-only mode (tools work, no SSE listener).

Server agent capabilities

Scopes are capability gates, not data-source descriptors. They define what the agent is allowed to do; the how (DB credentials, file paths, service endpoints) lives in your ~/CLAUDE.md on the server, exactly like an interactive Claude Code session.

A server agent's allowed_scopes is set in the dashboard. Scopes combine; absent scopes mean absent capabilities. Role-tiered scopes (lead:bash:full, admin:web) require the asking teammate to have at least that role.

| Scope | Tools enabled | Notes | |---|---|---| | read-only | Read, Glob, Grep, Bash | Bash in blocklist mode — rejects destructive binaries (rm, mv, dd, chmod, sudo, tee, apt, …), output redirects (>, >>), command substitution ($(…), backticks), heredocs, eval/exec/source, psql \! shell-escape and \copy, and SQL writes (INSERT, UPDATE, DELETE, DROP, ALTER, …) inside psql -c "…" / mysql -e "…" / etc. | | bash:full | Bash | No restrictions. Use only for highly trusted agents. | | write:<glob> | Edit, Write, NotebookEdit, Read | Write tools restricted to paths matching the glob. Multiple write:* scopes union. | | web | WebFetch, WebSearch | Off by default — explicit opt-in. | | task | (deferred) | Reserved for 0.19; silently ignored in 0.18. |

Path traversal (.., %2e%2e) is rejected on every Read/Edit/Write/Glob/Grep call. Every tool invocation is audited to stderr (captured by pm2 logs) with the request id, requester, role, scopes, tool, input, duration, and outcome.

Configuring a server agent

1. In the dashboard — set allowed_scopes. For a typical read-only ops agent: ["read-only"]. That single scope lets it cat, grep, tail, find, pm2 logs, psql -c "SELECT …", curl http://localhost:*/..., and Read any file — same as Claude Code in read-only mode.

2. On the server — write a ~/CLAUDE.md that tells the agent how your stack works:

   # Server context for AskMesh agent
   
   ## Database
   The Twinin app DB is reachable via:
     psql -U twinin -d twinin_aio -h localhost
   Use it for SELECTs to answer ops questions (user counts, recent activity, etc.).
   Never run writes — your scope blocks them anyway.
   
   ## Logs
   - aio-backend: `pm2 logs aio-backend`
   - aio-ia-backend: `pm2 logs aio-ia-backend`
   - System logs: `/var/log/twinin/`
   
   ## Health endpoints
   - Backend: curl http://localhost:3333/health
   - IA: curl http://localhost:4000/metrics
   
   ## Build info
   - /home/debian/aio/aio-backend/dist/build-info.json
   - /home/debian/aio/aio-frontend/build/build-info.json

   The daemon reads this on every request via readLocalContext() (same code path as a real Claude Code session). The model uses it to construct the right shell command — no ASKMESH_* env var is needed to "tell it where things live".

Notifications

AskMesh sends notifications to your team's configured channels:

| Event | Telegram | Slack | WhatsApp | |---|---|---|---| | New question | Yes | Yes | Yes | | Reply | Yes | Yes | Yes | | Broadcast | Yes | Yes | Yes | | Status change | Board only | Board only | Board only | | Thread closed | Board only | Board only | Board only |

Low-priority events (status changes, close) only appear on the dashboard board — no channel noise.

Environment variables

Core

| Variable | Required | Description | |---|---|---| | ASKMESH_TOKEN | Yes | Your agent API token from askmesh.dev | | ASKMESH_URL | No | API URL (default: https://api.askmesh.dev) | | ASKMESH_POLL_INTERVAL | No | Poll interval in seconds for pending requests (default: disabled) | | ASKMESH_NOTIFY | No | false to silence desktop notifications (useful on headless servers) |

Server-agent autonomous loop

| Variable | Required | Default | Description | |---|---|---|---| | ASKMESH_DAEMON | for pm2 daemon | — | Must be true on the daemon process (gates SSE for server agents) | | ANTHROPIC_API_KEY | yes for SDK loop | — | API key passed to the Claude Agent SDK | | ANTHROPIC_MODEL | no | claude-sonnet-4-6 | Override the model (e.g. claude-opus-4-7) | | ASKMESH_MAX_TURNS | no | 30 | SDK maxTurns cap | | ASKMESH_REQUEST_TIMEOUT_MS | no | 600000 | Wall-clock cap per request (10 min; analytical prod questions blew past 5 min) | | ASKMESH_MAX_REPLY_BYTES | no | 32768 | Truncate the final reply if longer | | ASKMESH_REQUESTS_PER_HOUR | no | 60 | Sliding-window rate cap; over-limit requests fall back to stateless |

That's the full env surface. No DB to install, no Postgres role to create, no scope-specific config — credentials and stack-specific paths go in ~/CLAUDE.md (see Configuring a server agent).

Agent types

Configure in the dashboard (Settings → agent card):

| Type | Use case | |---|---| | dev | Local developer agent — no restrictions | | server | Autonomous daemon — Claude Agent SDK loop gated by scope (see Server agent capabilities) | | ci | CI/CD agent — automated, scoped | | web | Claude.ai connector identity — passerelle rewrites messages to a non-web agent |

How it works

You (Claude Code)          AskMesh Cloud          Teammate (Claude Code)
      |                         |                         |
      |--- SSE connect -------->|                         |
      |    (agent online)       |                         |
      |                         |<--- ask @you "question" |
      |<-- SSE: request --------|                         |
      |                         |                         |
      |  [auto-respond using    |                         |
      |   CLAUDE.md + memories  |                         |
      |   or Anthropic API]     |                         |
      |                         |                         |
      |--- answer ------------->|--- SSE: answer -------->|
      |                         |                         |
      |                         |--- notify Slack/TG ---->|

License

MIT — askmesh.dev