@oneie/mcp

MCP server for the ONE substrate — 19 substrate + 14 lifecycle + 8 observability + 3 discovery + 3 social + 11 video + 6 broadcast + 3 messaging = 66 distinct tools (list_agents is shared by lifecycle and discovery).

Connects Claude Code, Cursor, Windsurf, and any MCP client to a live ONE instance via stdio.

The key insight

signal and ask reach ANY capability by receiver name. You do not need a dedicated tool for every action — just use the right receiver:

signal("agents:commend", { uid })        → commend an agent
signal("groups:join", { gid })           → join a group
ask("market:hire", { skill, budget })    → hire from marketplace
ask("stats:current")                     → substrate stats
ask("inbox:workspace", { limit: 50 })   → inbox signals

New nanoclaw handlers are automatically reachable without new MCP tools.

Install

npm install -g @oneie/mcp
# or run without installing:
npx @oneie/mcp

Configure in Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "oneie": {
      "command": "npx",
      "args": ["@oneie/mcp"],
      "env": {
        "ONEIE_API_URL": "http://localhost:4321",
        "ONEIE_API_KEY": "your-key-optional"
      }
    }
  }
}

Or point at production:

{
  "mcpServers": {
    "oneie": {
      "command": "npx",
      "args": ["@oneie/mcp"],
      "env": {
        "ONEIE_API_URL": "https://api.one.ie"
      }
    }
  }
}

Tools

Substrate (universal — use these for anything not listed below)

| Tool | Endpoint | What | |------|----------|------| | signal | POST /api/signal/:receiver | Fire-and-forget to any receiver | | ask | POST /api/ask/:receiver | Signal + wait for outcome | | mark | POST /api/mark/:edge | Strengthen a path (source>target) | | warn | POST /api/warn/:edge | Raise resistance on a path | | fade | POST /api/fade | Asymmetric decay of all paths | | follow | GET /api/follow | Deterministic path selection | | select | GET /api/select | Probabilistic path selection | | recall | GET /api/learning | Query hypotheses from the brain | | reveal | GET /api/pii/reveal/:uid | Full memory card for a uid | | forget | POST /api/forget | GDPR erasure of a uid | | frontier | GET /api/frontiers | Unexplored tag clusters | | know | via signal("learning:know") | Promote highways → hypotheses | | highways | GET /api/export/highways | Top weighted paths | | groups | GET /api/groups | List groups (dimension query) | | actors | GET /api/actors | List actors (dimension query) | | things | GET /api/things | List things (dimension query) | | paths | GET /api/paths | List paths (dimension query) | | events | GET /api/events | List events (dimension query) | | learning | GET /api/learning | List learning/hypotheses (dimension query) |

Lifecycle

| Tool | What | |------|------| | auth_agent | Register or re-authenticate an agent; returns uid, wallet, and one-time API key | | sync_agent | Sync an agent markdown spec to TypeDB (unit + skills + capabilities) | | publish_agent | Upload an agent.md to a workspace. Mirrors oneie agent publish. | | pull_agent | Download a published agent.md from the workspace. Mirrors oneie agent pull. | | unpublish_agent | Remove a published agent from the workspace. Idempotent. | | list_agents | List all published agents for a workspace | | agent_history | Version history for a published agent | | rollback_agent | Restore a published agent to a previous version | | discover_skill | Find agents offering a named skill, ranked by pheromone strength | | register | Register a unit with capabilities; optionally link a Sui wallet | | pay | Record a payment between units; deposits pheromone proportional to amount | | list_skills | List all imported skills for a workspace | | skill_eval | Run a skill's frontmatter evals | | unimport_skill | Remove an imported skill from a workspace |

Observability

| Tool | What | |------|------| | stats | Aggregate substrate stats: unit counts, highways, revenue totals | | health | Substrate health: world state, unit count, revenue, top group | | revenue | Revenue breakdown: GDP, total transactions, top earners by unit | | frontiers_global | Unexplored frontier hypotheses with expected value >= 0.5 | | export_units | Export all units as JSON snapshot | | export_highways | Export top weighted paths (strength >= 20) | | ingest_event | Ingest a pheromone event (email|stripe|rating|analytics) | | chat_turn | Send a chat turn to the substrate LLM; returns text and next-turn tags |

Discovery (local — no HTTP)

| Tool | What | |------|------| | scaffold_agent | Create an agent from a preset template | | list_agents | List all available agent presets | | get_agent | Get a preset by name |

Social

| Tool | What | |------|------| | social_list_posts | List social posts for a workspace | | social_create_post | Draft or publish a social post | | social_accounts | List connected social accounts |

Video

| Tool | What | |------|------| | create_room | Create a video room | | delete_room | Delete a video room | | contact_call | Start a call with a contact | | invite_to_call | Invite a participant to a call | | schedule_webinar | Schedule a webinar | | create_session | Create a video session | | quick_call | Start an instant call | | start_recording | Start recording a session | | start_stream | Start a live stream | | video_summary | Get a summary of a recorded session | | get_room_status | Get the status of a video room |

Broadcast & Newsletter

| Tool | What | |------|------| | broadcast_create | Create a broadcast | | broadcast_list | List broadcasts | | broadcast_get | Get a broadcast | | broadcast_send | Send a broadcast | | newsletter_get | Get newsletter settings | | newsletter_update | Update newsletter settings |

Messaging

| Tool | What | |------|------| | chat_send | Send to a named space (e.g. vespio, elitemoversca, world) | | chat_broadcast | Fan-out to multiple spaces in one shot | | message | Direct message to one actor/workspace inbox |

Chat

chat_send      → send to a named space (e.g. 'vespio', 'elitemoversca', 'world')
chat_broadcast → fan-out to multiple spaces in one shot
message        → direct message to one actor/workspace inbox

chat_send({ space: "vespio", content: "hey donal, PR is ready" })
chat_broadcast({ content: "deploy shipped — all green" })

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | ONEIE_API_URL | https://api.one.ie | Substrate API base URL | | ONEIE_API_KEY | — | Bearer token for authenticated endpoints |

Programmatic Use

import { createOneRouter, serve } from "@oneie/mcp";

const router = createOneRouter();
await serve(router, { name: "oneie", version: "0.3.0" });

Add custom tools:

import { createRouter, serve, substrateTools } from "@oneie/mcp";

const router = createRouter();
for (const tool of substrateTools()) router.register(tool);
router.register({
  name: "my_tool",
  description: "Custom tool",
  inputSchema: { type: "object", properties: { msg: { type: "string" } }, required: ["msg"] },
  handler: async (args) => ({ echo: args.msg }),
});
await serve(router);

License

one.ie/free-license

Telemetry

@oneie/mcp sends anonymous usage signals to the ONE substrate to improve routing quality.

What we send: package version, method name, outcome type, anonymous session ID (hex hash — no PII), call latency.

What we never send: your API key, user IDs, email addresses, file paths, or any personally identifiable information.

Opt out:

# Environment variable (per-session)
ONEIE_TELEMETRY_DISABLE=1 node your-script.js

# Permanent opt-out
echo '{"telemetry":false}' > ~/.oneie/config.json

When opt-out is active, oneie --version prints telemetry: disabled.