@dataforge/mcp

MCP stdio adapter for DataForge — connects Claude Desktop/Code to your workspace.

Status: Preview (0.1.0-preview.0). Published with npm preview tag. The stable agent contract remains DataForge CLI/API; this adapter is a thin MCP projection and may change in preview versions.

Quick Start

Claude Code

claude mcp add dataforge-mcp -- \
  env DATAFORGE_API_URL=https://api.dev-growthsystemes.com \
      DATAFORGE_MCP_API_KEY=df_... \
      DATAFORGE_WORKSPACE_ID=... \
  npx @dataforge/mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "dataforge": {
      "command": "npx",
      "args": ["@dataforge/mcp"],
      "env": {
        "DATAFORGE_API_URL": "https://api.dev-growthsystemes.com",
        "DATAFORGE_MCP_API_KEY": "df_...",
        "DATAFORGE_WORKSPACE_ID": "your-workspace-uuid"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | DATAFORGE_API_URL | Yes | Backend URL | | DATAFORGE_MCP_API_KEY | Yes | API key with mcp.read scope | | DATAFORGE_WORKSPACE_ID | Yes | Target workspace UUID | | DATAFORGE_MCP_SURFACE | No | Surface profile: preview-stable (default), preview-full, internal |

Surface Profiles

| Profile | Tools | Description | |---------|-------|-------------| | preview-stable | 34 | BaaS public surface: read-only discovery/query/search/traverse, context, usage, and signed-plan lifecycle tools. | | preview-full | Preview superset | Additional preview tools for controlled validation; backend gating remains authoritative. | | internal | All | Full tool surface (staging/development only). |

df_apply_plan, df_create_handoff, and df_plan_revoke are visible in preview-stable because they are plan-gated BaaS verbs. They do not permit direct mutation: the backend still requires FEATURE_PLAN_ARTIFACTS, the caller's scopes, plan verification, idempotency, policy, and audit checks.

Architecture

This package is a thin stdio-to-HTTP proxy. The backend is the gating authority — the package forwards JSON-RPC messages and lets the server enforce surface filtering.

stdin (JSON-RPC) -> @dataforge/mcp -> POST /api/mcp -> stdout (JSON-RPC)

License

MIT