{"_id":"@agiflowai/openclaw-mcp-in","name":"@agiflowai/openclaw-mcp-in","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agiflowai/openclaw-mcp-in","version":"0.1.0","description":"OpenClaw plugin for MCP (Model Context Protocol) server integration","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","openclaw":{"extensions":["dist/index.js"]},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","publish":"npm run build && node scripts/publish.mjs"},"dependencies":{"@agiflowai/one-mcp":"^0.3.12"},"devDependencies":{"@types/node":"^25.3.5","openclaw":"^2026.3.2","terser":"^5.46.0","tsup":"^8.5.1","typescript":"^5.9.3"},"license":"BUSL-1.1","peerDependencies":{"openclaw":">=2026.1.0"},"_id":"@agiflowai/openclaw-mcp-in@0.1.0","gitHead":"6d7377fe85f9f04004356887e4184eb44f833b5c","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-cmc8TZs5vw+NLH/BMWzp6rmBV/wGHK95qml1YavUmmH0bNfLtNyfRyRaZVcdWR80W/gt1rCpmVY4XwCWRXKIxQ==","shasum":"0922decc549ed0fc8dd524b7f2ac2adafa06ee05","tarball":"https://registry.npmjs.org/@agiflowai/openclaw-mcp-in/-/openclaw-mcp-in-0.1.0.tgz","fileCount":7,"unpackedSize":36239,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGqqcyzr/XUE3uzrS9vuO2MdmQNNXUzaUQIA5iGoXnM1AiAFeO+JSre0WAjr5Ar/nizgGjkCli07CZkBFVXLGxYmGw=="}]},"_npmUser":{"name":"agiflow-ai","email":"agiflow.ai@gmail.com"},"directories":{},"maintainers":[{"name":"agiflow-ai","email":"agiflow.ai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-mcp-in_0.1.0_1772776338683_0.40347908560703116"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-06T05:52:18.260Z","0.1.0":"2026-03-06T05:52:18.845Z","modified":"2026-03-06T05:52:19.107Z"},"maintainers":[{"name":"agiflow-ai","email":"agiflow.ai@gmail.com"}],"description":"OpenClaw plugin for MCP (Model Context Protocol) server integration","license":"BUSL-1.1","readme":"# OpenClaw MCP Plugin\n\nConnect your OpenClaw agents to **76+ MCP tools** from multiple servers with progressive disclosure — reducing initial token usage by 90%+.\n\n## Why Use This?\n\nWithout this plugin, connecting to multiple MCP servers loads ALL tools at startup:\n- 5 MCP servers × 15 tools each = **~40,000 tokens consumed before you even start**\n\nWith this plugin using progressive discovery:\n- Only 3 meta-tools loaded = **~500 tokens**\n- Tools load on-demand when you actually need them\n\n**Result: 90%+ reduction in initial token usage + cleaner agent context**\n\n## Quick Start\n\n### 1. Install the Plugin\n\n```bash\n# From your openclaw-mcp-plugin directory\nnpm install\nnpm run build\n\n# Install into OpenClaw\nopenclaw plugins install --link /path/to/openclaw-mcp-plugin\n```\n\n### 2. Create MCP Configuration\n\nCreate `mcp-config.yaml` in one of these locations (checked in order):\n\n| Location | Scope |\n|----------|-------|\n| `{agentDir}/mcp-config.yaml` | Per-agent (e.g. `~/.openclaw/agents/research/agent/mcp-config.yaml`) |\n| `{workspaceDir}/mcp-config.yaml` | Per-workspace |\n| `pluginConfig.configFilePath` | Global fallback |\n\n```yaml\nmcpServers:\n  playwright:\n    command: playwright-mcp\n    args:\n      - mcp-serve\n      - --mode\n      - extension\n    config:\n      instruction: |\n        Playwright browser automation. Use for web browsing, automation, and testing.\n\n  github:\n    command: npx\n    args:\n      - \"-y\"\n      - \"@modelcontextprotocol/server-github\"\n    env:\n      GITHUB_TOKEN: \"${GITHUB_TOKEN}\"\n\n  web-search:\n    type: http\n    url: \"https://api.example.com/mcp\"\n    headers:\n      Authorization: \"Bearer ${API_KEY}\"\n```\n\n### 3. Configure OpenClaw\n\nUpdate your `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"openclaw-mcp\": {\n        \"enabled\": true,\n        \"config\": {\n          \"serverId\": \"openclaw-mcp\"\n        }\n      }\n    }\n  },\n  \"tools\": {\n    \"alsoAllow\": [\"group:plugins\"]\n  }\n}\n```\n\n### 4. Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n## Usage\n\nThe plugin exposes 3 meta-tools that provide progressive access to all MCP capabilities:\n\n### Step 1: List Available Tools\n\n```json\n{\n  \"tool\": \"mcp__list_tools\",\n  \"params\": {\n    \"capability\": \"browser\"\n  }\n}\n```\n\nReturns tools grouped by server with capability summaries. Optionally filter by `capability` keyword or `serverName`.\n\n### Step 2: Get Tool Schemas\n\n```json\n{\n  \"tool\": \"mcp__describe_tools\",\n  \"params\": {\n    \"toolNames\": [\"browser_navigate\", \"browser_screenshot\"]\n  }\n}\n```\n\nReturns detailed input schemas, descriptions, and server information for the requested tools.\n\n### Step 3: Execute Tools\n\n```json\n{\n  \"tool\": \"mcp__use_tool\",\n  \"params\": {\n    \"toolName\": \"browser_navigate\",\n    \"toolArgs\": {\n      \"url\": \"https://example.com\"\n    }\n  }\n}\n```\n\n## Per-Agent Configuration\n\nDifferent agents can connect to different MCP servers by placing `mcp-config.yaml` in their agent directory:\n\n```\n~/.openclaw/agents/\n├── default/agent/mcp-config.yaml    ← default agent's MCP servers\n├── research/agent/mcp-config.yaml   ← research agent gets different servers\n└── coding/agent/mcp-config.yaml     ← coding agent gets its own set\n```\n\nAgents sharing the same config file reuse the same MCP connections. Agents without a local config fall back to the workspace or global config.\n\n## Environment Variables & Secrets\n\nMCP configs reference secrets via `${VAR}` syntax. There are two ways to provide them:\n\n### Option A: Shell Environment (simplest)\n\nSet env vars in your shell before starting the gateway:\n\n```bash\nexport GITHUB_TOKEN=\"ghp_abc123\"\nopenclaw gateway start\n```\n\n### Option B: OpenClaw Plugin Config (recommended)\n\nDeclare secrets in `openclaw.json` and let OpenClaw's config system resolve them:\n\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"openclaw-mcp\": {\n        \"enabled\": true,\n        \"config\": {\n          \"env\": {\n            \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\",\n            \"LINEAR_API_KEY\": \"${LINEAR_API_KEY}\",\n            \"SLACK_TOKEN\": \"${SLACK_BOT_TOKEN}\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nOpenClaw resolves `${VAR}` references in config at load time, then the plugin injects them into `process.env` before MCP servers connect. This works with OpenClaw's env substitution pipeline.\n\n**Precedence**: Shell env (highest) → `pluginConfig.env` → one-mcp interpolation.\n\nExisting env vars are never overwritten — your shell environment always takes priority.\n\n## Configuration Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `configFilePath` | `mcp-config.yaml` | Fallback path to MCP configuration file |\n| `serverId` | `openclaw-mcp` | Unique identifier for this MCP instance |\n| `noCache` | `false` | Disable configuration caching |\n| `env` | — | Map of env vars to inject before MCP config is read |\n\n## How It Works\n\n1. **Plugin loads**: Registers 3 meta-tools (`mcp__list_tools`, `mcp__describe_tools`, `mcp__use_tool`)\n2. **Agent invoked**: Tool factory resolves per-agent `mcp-config.yaml` path from `ctx.agentDir`\n3. **First tool call**: Lazily initializes MCP connections for that agent's config\n4. **Agent discovers**: Calls `mcp__list_tools` to browse available tools\n5. **Agent describes**: Calls `mcp__describe_tools` for specific tool schemas\n6. **Agent executes**: Calls `mcp__use_tool` with the correct arguments\n\nThis is the **progressive disclosure pattern** — tools are discovered on-demand rather than loaded upfront.\n\n## Troubleshooting\n\n### Plugin not loading?\n\n```bash\n# Check plugin status\nopenclaw plugins list\n\n# Check gateway logs\ntail -f ~/.openclaw/logs/gateway.log | grep openclaw-mcp\n```\n\n### MCP servers not connecting?\n\n```bash\n# Test your config directly with one-mcp CLI\nnpx @agiflowai/one-mcp list-tools --config mcp-config.yaml\n```\n\n### Tools showing \"Method not found\" errors?\n\nThese are expected for servers that don't support `prompts/list`. The errors are harmless and don't affect tool functionality.\n\n### Env var not being picked up?\n\nCheck the resolution order:\n1. Is it set in your shell? (`echo $VAR_NAME`)\n2. Is it declared in `pluginConfig.env`?\n3. Does the `mcp-config.yaml` reference it with `${VAR_NAME}` syntax?\n\n## Advanced: Skills\n\nYou can also add skills (reusable prompt templates) to your MCP config:\n\n```yaml\nmcpServers:\n  # ... your servers\n\nskills:\n  paths:\n    - ~/.openclaw/skills\n```\n\nSkills are discovered through `mcp__list_tools` and `mcp__describe_tools` just like MCP tools, using the `skill__` prefix.\n\n## License\n\nMIT\n\n## Credits\n\nBuilt on [@agiflowai/one-mcp](https://github.com/AgiFlow/aicode-toolkit/tree/main/packages/one-mcp) — the progressive MCP proxy server.\n","readmeFilename":"README.md","_rev":"1-bdace73b7701bb5a3c58cbb79b44be13"}