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/asks	ask
GET /api/v1/asks	asks_list
GET /api/v1/asks/{ask_id}	ask_show
POST /api/v1/memory/decisions	memory_append_decision

A few operations carry a hand-written name where the derived one would read badly — POST /asks is ask, not ask_create, because that is the verb a model reaches for.

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.

The ask tools

ask is usually the first tool a chat client calls: read-only Q&A about the project, answered with citations. It takes question plus optional pipeline and target, runs the explorer synchronously (5–30 seconds, so the client blocks), and returns the completed ask including its cited_entities. asks_list browses the history; ask_show fetches one ask with its full citations hydrated.

Caution

ask is a pure proxy onto POST /api/v1/asks, which means the explorer’s sql grant reaches your real warehouse — an ask driven from Claude Desktop or Cursor issues live queries, costs warehouse credits, and needs working credentials, exactly as valved ask does. It stays read-only throughout (see the core loop). If the model passes a target that isn’t a valid target name, the REST layer returns 400 and the client sees a tool error rather than an answer.

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).