npm package: @jpaguirrech/juanmcp
Description: OpenClaw plugin: MCP client that registers remote MCP tools as agent tools. Configure your own MCP server URLs in openclaw.json.
Latest version: 0.3.0

# Juan MCP (juanmcp)

OpenClaw plugin that connects to one or more MCP (Model Context Protocol) servers and registers their tools as native OpenClaw agent tools. Any OpenClaw instance with this plugin installed can consume **any** remote MCP server—add your own URLs in config; no hardcoded servers.

## Overview

- **Problem:** OpenClaw has no built-in support for adding MCP servers as tool sources (unlike Cursor's `mcpServers`).
- **Solution:** This plugin acts as an MCP client: it connects to configured MCP URLs, fetches `tools/list`, and registers each MCP tool with OpenClaw. When the agent calls a tool, the plugin forwards the call to the MCP server and returns the result.

## Requirements

- OpenClaw gateway (2026.x)
- Node.js 18+ (for plugin runtime)
- MCP server(s) reachable via HTTP (SSE or Streamable HTTP transport)

## Installation

**Quick setup** (installs plugin + config in one step):

```bash
npx @jpaguirrech/juanmcp
# With custom servers:
npx @jpaguirrech/juanmcp --servers servers.json
```

See [docs/INSTALL.md](docs/INSTALL.md) for full options.

**Manual install:**

```bash
openclaw plugins install @jpaguirrech/juanmcp
```

Then add plugin config and `tools.allow` to `openclaw.json` (see [docs/INSTALL.md](docs/INSTALL.md)).

## Configuration

In `openclaw.json` (or your main config file):

```json
{
  "plugins": {
    "entries": {
      "juanmcp": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "id": "my-calendar",
              "url": "https://your-mcp-host.example.com/mcp",
              "headers": {}
            }
          ]
        }
      }
    }
  },
  "tools": {
    "allow": ["mcp_my_calendar_*"]
  }
}
```

- **servers**: Array of MCP server entries. Add any MCP server URL you want to use.
- **id**: Short identifier for this server (used as tool name prefix, e.g. `mcp_my_calendar_<tool_name>`). Use only letters, numbers, and hyphens.
- **url**: Base URL of the MCP server (HTTP/SSE or Streamable HTTP). Must be reachable from the OpenClaw gateway.
- **bearerToken**: Bearer token for `Authorization: Bearer <token>`. Use `$ENV_VAR` to read from environment (e.g. `$MCP_CALENDAR_TOKEN`).
- **headers**: Optional key-value map for custom headers (merged with bearerToken if both set).

## Project structure

```
pluggins-openClaw/
├── README.md                 # This file
├── openclaw.plugin.json      # Plugin manifest and config schema
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts              # Plugin entry: register MCP client and tools
└── docs/                     # Optional extra documentation
```

## Publishing to the marketplace (npm)

OpenClaw plugins are distributed via **npm**. There is no separate plugin marketplace; users install with:

```bash
openclaw plugins install <package-name>
```

To make this plugin available to everyone:

1. **Publish to npm** (use a scope if you prefer, e.g. `@jpaguirrech/juanmcp`):
   ```bash
   cd pluggins-openClaw
   npm run build
   npm publish --access public
   ```
   For scoped packages: `npm publish --access public` (so it is public without paying for private packages).

2. **Optional:** Submit or list your package in community indexes (e.g. OpenClaw docs, Awesome OpenClaw, or a catalog file at `~/.openclaw/plugins/catalog.json`) so others can discover it. The official docs mention optional catalog paths: `OPENCLAW_PLUGIN_CATALOG_PATHS`.

3. **Install for users:** Once published, anyone can run:
   ```bash
   openclaw plugins install @jpaguirrech/juanmcp
   ```
   and then add their own `servers` in config—no default or hardcoded MCP URLs.

**Note:** This plugin does not ship any default MCP URLs. Users must configure their own `servers` in `openclaw.json`.

## Development

- All code, comments, and documentation are in English.
- Communication with maintainers may be in another language; the repo stays English-only.

## References

- [OpenClaw – Plugin agent tools](https://docs.openclaw.ai/plugins/agent-tools)
- [OpenClaw – Plugins](https://docs.openclaw.ai/tools/plugin)
- [MCP – Transports](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports)
- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)