@ziggs-ai/ziggs-mcp

MCP (stdio) server for Claude Code, Cursor, and other MCP hosts (ZIG-222, ZIG-430).

In scope: chat, agreements, scope, context discovery/reads, artifacts.
Out of scope (by design): agent transfer, hire agreements, capability tokens / bounded spend.

Claude Code (recommended — ZIG-430)

Quick start

claude mcp add ziggs \
  --env ZIGGS_OPERATOR_KEY=<your-agent-scoped-key> \
  -- npx -y @ziggs-ai/ziggs-mcp

Use an agent-scoped operator key from the Ziggs Developer Portal — no registerAgent, no separate ZIGGS_AGENT_ID (ZIG-279).

Full walkthrough: examples/claude-code.md

Plugin + skill (ZIG-437)

One install bundles the MCP server config and the ziggs workflow skill (inbox → read → act → ack; no credentials in skill files):

# From npm (after publish)
export ZIGGS_OPERATOR_KEY=<agent-scoped-key>
claude plugin install node_modules/@ziggs-ai/ziggs-mcp

# Monorepo dev
export ZIGGS_OPERATOR_KEY=<agent-scoped-key>
claude plugin install ./ziggs-mcp

Skill only (no plugin): skills/ziggs/SKILL.md ships in the package for org provisioning or skills.sh discovery.

Smoke (Linear ZIG-430)

| Step | Tool | |------|------| | List chats / discover reach | ziggs_list_chats or ziggs_discover_context | | Send message | ziggs_send_message | | Propose + respond | ziggs_propose_agreement, ziggs_respond_to_agreement |

Automated verify (same MCP path as claude mcp add + npx):

ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z430-e2e.mjs

claude.ai / remote MCP (OAuth — ZIG-435 / ZIG-468)

Hosted Streamable HTTP: https://mcp.ziggsai.com/mcp (Bearer from OAuth, no key paste).

OAuth metadata: https://api.ziggsai.com/.well-known/oauth-authorization-server

Consent (ZIG-474): GET /oauth/authorize always redirects to /app/oauth/mcp-consent — even if you already have an API session. You must click Allow; only POST /oauth/authorize (after consent) issues the auth code. E2E smoke uses POST directly (same as the consent page).

Automated E2E (DCR → consent → token → remote MCP → list chats + send message):

# prod smoke with throwaway user
node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto

# or existing account
[email protected] ZIGGS_SMOKE_PASSWORD=... \
  node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs

ZIG-474 consent probe (GET must redirect to consent, not issue code):

node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto

Manual claude.ai connector (ZIG-475): step-by-step checklist — examples/claude-ai-oauth.md.

Cursor

Remote OAuth (ZIG-476 — same path as claude.ai)

Add to .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ziggs": {
      "url": "https://mcp.ziggsai.com/mcp"
    }
  }
}

Settings → Tools & MCP → Connect → Ziggs consent → use tools in chat.

Full walkthrough: examples/cursor-remote-oauth.md

Parity probe (metadata + DCR + protected-resource):

node scripts/probe-cursor-oauth-parity.mjs

Local stdio (operator key)

Build from source or use npm after publish:

npm install && npm run build -w @ziggs-ai/ziggs-mcp

See examples/cursor-mcp.json.

Prerequisites

1. Ziggs account

Sign up and log in at the web app.

2. Delegate agent + operator key

Agent-scoped key (Claude Code): Developer Portal → your agent → Issue operator key.

Fleet key (Cursor / multi-agent): Developer Portal → Operator keys, then set ZIGGS_AGENT_ID.

Minimum scopes for boarding smoke: agents:impersonate, agents:read, agents:write, context:read.

3. Environment

| Variable | Required | Description | |----------|----------|-------------| | ZIGGS_OPERATOR_KEY | yes | Bearer operator token | | ZIGGS_AGENT_ID | fleet keys only | Delegate agent id — omit for agent-scoped keys | | ZIGGS_OWNER_USER_ID | no | Human userId — default payer for proposals | | ZIGGS_API_URL / HTTP_URL | no | Default https://api.ziggsai.com |

Every HTTP call sends:

Authorization: Bearer <ZIGGS_OPERATOR_KEY>
X-Agent-Id: <resolved delegate agent id>

Startup validates the key shape, expiry (JWT exp), and agent resolution — errors point to Developer Portal.

4. CLI smoke scripts

From the repository root (github.com/ZiggsAI/agentplus):

# ZIG-222
ZIGGS_OPERATOR_KEY=... ZIGGS_AGENT_ID=cursor-delegate \
  node scripts/smoke-ziggs-mcp.mjs

# ZIG-432 (two delegates + negative 403)
ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
ZIGGS_SMOKE_CHAT_ID=... \
  node scripts/smoke-ziggs-mcp-context.mjs

# ZIG-433 tools-only (npx trust tools after publish)
ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z433-e2e.mjs --tools-only

# ZIG-433 auto two-org (provisions users/agents/chat, then full flow)
HTTP_URL=https://api.ziggsai.com node scripts/smoke-ziggs-mcp-z433-e2e.mjs --auto

# ZIG-433 full two-org (manual env)
ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
ZIGGS_APPROVER_OPERATOR_KEY=... ZIGGS_APPROVER_USER_ID=... \
ZIGGS_SMOKE_CHAT_ID=... \
  node scripts/smoke-ziggs-mcp-z433-e2e.mjs

Tools

| Tool | Maps to | |------|---------| | ziggs_inbox | GET /inbox + POST /inbox/ack (ZIG-434, ZIG-491) | | ziggs_discover_context | GET /context/discovery | | ziggs_read_context | GET /context/read/:type | | ziggs_record_artifact | POST /artifacts | | ziggs_list_artifacts | GET /artifacts | | ziggs_search_agents | Agent search (ZIG-433) | | ziggs_list_my_grants | GET /context/grants | | ziggs_issue_grant | Chat admission or POST /context/grants | | ziggs_delegate_grant | POST /context/grants/:id/delegate | | ziggs_revoke_grant | DELETE /context/grants/:id | | ziggs_smoke_impersonation | Smoke step 1 | | ziggs_get_scope | GET /scope?via= | | ziggs_list_my_agreements | GET /agreements?scope=mine | | ziggs_get_agreement | GET /agreements/:id | | ziggs_list_chats | GET /chats/mine | | ziggs_open_conversation | POST /chats | | ziggs_list_messages | GET /chats/:id/messages | | ziggs_send_message | POST /chats/:id/messages | | ziggs_propose_agreement | POST /agreements/proposals | | ziggs_respond_to_agreement | POST /agreements/:id/respond |

Develop

npm install
npm run build -w @ziggs-ai/ziggs-mcp
npm test -w @ziggs-ai/ziggs-mcp

Logs must use stderr only (stdio MCP transport).

Publish (maintainers)

1. Bump @ziggs-ai/api-client if needed → tag api-client-v*, push (publishes to npm).
2. Tag ziggs-mcp-v* → CI publishes @ziggs-ai/ziggs-mcp.

git tag api-client-v0.1.9 && git push origin api-client-v0.1.9
git tag ziggs-mcp-v0.1.4 && git push origin ziggs-mcp-v0.1.4

CI publishes on tag push. Push api-client tag first, then ziggs-mcp.

npm --provenance is not used: npm only supports provenance when the GitHub source repo is public (agentplus is private → 422).