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

Server	Description	URL
mulesoft-code-mcp	Search + execute over MuleSoft operations with OAuth and write guardrails	http://127.0.0.1:3000/mcp

Tools Exposed

Tool	Purpose	Typical use
search	Finds ranked operations from Exchange portal + OpenID context	"list assets", "exchange api", "oauth token"
execute	Validates and executes operation by operation_id	Read and write calls with typed validation
auth_status	Returns auth status for current caller	Preflight before execute

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