MuleSoft Code MCP

Model Context Protocol (MCP) is a standardized way for LLMs to use external systems through tools. This repository provides a focused remote MCP server for MuleSoft APIs so agents can discover operations and execute validated API calls with a fixed low-context tool surface.

Design references:

• Cloudflare Code Mode MCP

• Anthropic: Building Effective Agents (advanced tool use)

The server supports streamable-http transport via /mcp.

Server in this Repository

Related MCP server: cocoon

Tools Exposed

Why Better Than Official MCP Patterns

Compared to official/provider MCP servers that expose many endpoint-specific tools, this implementation is better for agent execution quality:

• Lower context pressure: fixed 3 tools instead of endpoint-tool explosion.

• Better tool selection: agent maps intent with search, then executes one explicit operation_id.

• Stronger safety: writes require both server policy and per-request confirmation token.

• Better runtime behavior: response truncation, read caching, and persisted catalog cache reduce latency and token waste.

Access from Any MCP Client

If your MCP client supports remote MCP directly:

{
  "mcpServers": {
    "mulesoft-code-mcp": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

If your client needs a command bridge:

{
  "mcpServers": {
    "mulesoft-code-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp"],
      "env": {
        "MCP_REMOTE_HEADERS": "{\"x-user-id\":\"default\"}"
      }
    }
  }
}

Quick Start

cd mulesoft
npm install
npm run build
npm test

Seed access token from environment:

MULESOFT_ACCESS_TOKEN='<token>' npm run seed:token

Start server:

TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64='<seed-output-key>' \
PORT=3000 HOST=127.0.0.1 npm run dev

Smoke test:

curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp

Tool Calling Flow

1. Call auth_status.

2. Call search with intent (for example, list exchange assets).

3. Pick an operation_id.

4. Call execute with required params.

5. For writes: call dry_run=true, then replay with confirm_write_token and ALLOW_WRITES=true.

Example search input:

{
  "query": "list exchange assets",
  "limit": 5
}

Example read execute input:

{
  "operation_id": "GET /exchange/api/v2/assets"
}

Example write execute dry run:

{
  "operation_id": "DELETE /exchange/api/v2/assets/{assetId}",
  "path_params": {
    "assetId": "my-asset"
  },
  "dry_run": true
}

Configuration

Key environment variables:

• ALLOW_WRITES (default false)

• REQUEST_TIMEOUT_MS

• MAX_RETRIES

• CATALOG_CACHE_PATH

• READ_CACHE_TTL_MS

• EXECUTE_MAX_BODY_BYTES

• EXECUTE_BODY_PREVIEW_CHARS

See .env.example for the full set.

Safety Model

• Mutating methods are blocked unless ALLOW_WRITES=true.

• Mutating calls require confirm_write_token from dry_run for exact request replay.

• Sensitive headers and body fields are redacted.

Performance Model

• Fixed 3-tool MCP surface to keep context small.

• Persisted catalog cache enables fast startup and asynchronous refresh.

• Conditional refresh for upstream metadata where available.

• Short TTL cache for repeated read calls (GET / HEAD).

• Execute body truncation controls context overhead.

Troubleshooting

• MCP Inspector connect failure: confirm URL is http://127.0.0.1:3000/mcp and server is running.

• AUTH_REQUIRED: seed token or complete OAuth bootstrap.

• Write blocked: set ALLOW_WRITES=true and use returned confirm_write_token.

• Sparse search results: include concrete resource terms (exchange, assets, oauth).

Development

• Source: src

• Tests: tests

• References: REFERENCES.md