MCP server

Valved ships an MCP server so you can drive your data platform by chatting with an AI client — Claude Desktop, Cursor, Claude Code, or any other MCP client. Ask “what pipelines do I have?” or “plan a pipeline that loads Stripe into the warehouse, then build it” and the model calls Valved’s tools for you.

How it works

The MCP server is a thin adapter over Valved’s REST API. Every non-streaming REST endpoint becomes an MCP tool automatically — so the tool catalog always mirrors the REST surface, and new Valved features show up as new tools with no extra work. It has no logic of its own: it translates each tool call into an HTTP request against the API that valved serve exposes.

┌──────────────┐   MCP (stdio/http)   ┌──────────────┐   HTTP    ┌──────────────┐
│ Claude / IDE │ ───────────────────► │ valved       │ ────────► │ valved       │
│ (MCP client) │ ◄─────────────────── │ mcp-serve    │ ◄──────── │ serve (REST) │
└──────────────┘                      └──────────────┘           └──────────────┘

Prerequisites

1. Valved’s REST API is running. Start it with valved serve (defaults to http://127.0.0.1:8765). The MCP server fetches the OpenAPI schema from <server-url>/api/openapi.json at startup to generate its tools.
2. A Valved API token. valved serve bootstraps one to .valved/token on first run; you can also mint/rotate one with valved auth rotate. The MCP server resolves the token in this order: --token flag → VALVED_API_TOKEN env var → .valved/token file.

The command

valved mcp-serve [OPTIONS]

  --transport [stdio|http]  Transport (default: stdio).
  --port INTEGER            Port for the http transport (default: 8766).
  --host TEXT               Host for the http transport (default: 127.0.0.1).
  --server-url TEXT         Valved REST API base URL (default: http://127.0.0.1:8765).
  --token TEXT              Bearer token override (default: discovered, see above).
  --log-level TEXT          Log level to stderr (default: WARNING).

• stdio (the default) is what Claude Desktop / Cursor / Claude Code spawn as a subprocess. In stdio mode stdout carries the JSON-RPC stream — all logging goes to stderr.
• http runs a long-lived Streamable HTTP endpoint at http://<host>:<port>/mcp for remote agents. (--transport ws is a deprecated alias for http.)

Prefer $VALVED_API_TOKEN (or .valved/token) over a literal --token, which lands in shell history / ps.

Register with a client

Claude Desktop

Edit the config file and add Valved under mcpServers, then quit and reopen Claude Desktop.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "valved": {
      "command": "valved",
      "args": ["mcp-serve"],
      "env": { "VALVED_API_TOKEN": "your-token-here" }
    }
  }
}

Cursor

Open Settings → MCP → Add new server and paste the same JSON. Cursor spawns valved mcp-serve on demand.

Claude Code

claude mcp add valved -- valved mcp-serve
claude mcp list          # 'valved' should appear

Set VALVED_API_TOKEN in the environment Claude Code runs in, or pass --token in the args.

Tool naming

Tools are named <resource>_<verb>, derived from the REST method and path:

REST	MCP tool
GET /api/v1/plans	plans_list
POST /api/v1/plans	plan_create
GET /api/v1/plans/{plan_id}	plan_show
POST /api/v1/builds	build_run
POST /api/v1/runs	run_pipeline
POST /api/v1/runs/{run_id}/resume	run_resume
POST /api/v1/memory/decisions	memory_append_decision

Streaming endpoints (the run event stream) are not exposed as tools — MCP tools/call is synchronous request/response. Connect to the REST stream directly if you need live events.

Verify it works

In your chat client, ask:

what Valved pipelines do I have?

The model should call pipelines_list and report your pipelines. From there you can drive the full lifecycle — plan_create → build_run → run_pipeline — without touching the CLI.

Consuming external MCP servers

The reverse direction — Valved’s agents consuming external MCP servers (Snowflake MCP, dbt MCP, GitHub MCP) as skills — is managed with valved mcp-servers add/list/remove, which is distinct from valved mcp-serve (Valved as a server).