MCP Servers

Two servers. One graph.

Model Context Protocol servers that give AI agents direct read/write access to your product graph. Local for offline, single-file use. Cloud for Postgres-backed, multi-product collaboration. Both open source. Both free.

local@unified-product-graph/mcp-server

A single .upg file on your machine.

$npx @unified-product-graph/mcp-server --file ./my-product.upg

Storage: .upg file (JSON), portable and git-friendly
Best for: Solo, offline, version-controlled work

cloud@unified-product-graph/cloud-server

Postgres-backed, built for teams.

$docker compose up -d

Setup: Docker · self-hosted, open source
Storage: Postgres (multi-product, full-text search)
Best for: Teams, collaboration, webhooks

What it enables

An agent that can reason over your product

The graph is a file the server reads and writes directly. Watch one conversation move through it:

Read your product's structure — personas, outcomes, opportunities, solutions.

Claude Code · UPG MCP

Quick start

Running in two steps

1Add to your AI tool's MCP config

.mcp.json

{
  "mcpServers": {
    "upg-local": {
      "command": "npx",
      "args": ["@unified-product-graph/mcp-server", "--file", "./my-product.upg"]
    }
  }
}

./my-product.upg is your graph file, created on first run and loaded every time after. Omit --file and the server finds a .upg in your workspace, or creates product.upg. Launched over stdio by your AI tool. See the CLI to run it by hand.

2Start a conversation

“What's in my product graph?”get_product_context

“Add a persona called Solo Product Creator…”create_node

“What opportunities exist for that persona?”search_nodes

The agent picks the right tool and calls it. You just describe what you want.

Tools

93 tools across 11 groups

AI agents discover these automatically via the MCP tools/list method. Local and cloud share most signatures; cloud adds collaboration tools.

Context & Session4

Graph overview, session state, product context, and digest tools.

Nodes14

Create, read, update, delete, search, move, batch, and deduplicate nodes.

Edges9

Create, read, delete, export, rename, and resolve edge types.

Areas & Change Log5

Areas, change log, and time-bounded change queries.

Workspace & Portfolios10

Workspace initialisation, product switching, portfolios, and cross-product edges.

Schema1

Entity schemas, valid children, entity metadata, and type labels.

Spec Introspection43

Spec introspection: approaches, playbooks, regions, domains, lenses, frameworks.

Cloud Sync3

Push and pull graph state to/from the UPG cloud.

Validation2

Validate the graph, detect anti-patterns, and run structural health checks.

Migrations1

Apply graph-wide status migrations, rewriting legacy lifecycle values to the current spec.

Skills1

Audit UPG skills for source-vs-deployed integrity.

Browse the full tool reference →312 entity types in the spec →

Agent workflows

How agents use the graph

Populate from scratch

Chain persona → job → need → outcome. Every create/update response scores completeness and lists missing fields.

> create persona "Solo Creator"

· create_node → n_a1 · 40%

> add its job, need, outcome

✓ chain created · 4 nodes

Build toward a view

The ontology is the framework. BMC, OKR, OST, GTM each map to a known set of entity types.

> populate a Business Model Canvas

· create_node business_model

· + value_proposition, channel …

✓ 9 BMC entities

Wire cross-domain

create_edge connects entities across hierarchies; the server infers the edge type from the pair.

> connect value_prop to persona

· create_edge (type inferred)

✓ value_proposition —serves→ persona

Analyse & fill gaps

get_graph_digest finds orphans and counts by type. Fill the gaps through conversation.

> what's floating?

· get_graph_digest

⚠ 3 orphans · 2 outcomes lack metrics

Local vs Cloud

Same protocol, different storage

Both servers share most tool signatures. Start local; move to cloud when you need teams.

Local

Cloud

Storage

.upg file (JSON)

Postgres

Products

One per file

Unlimited

In-memory

Postgres full-text

Collaboration

Via Git

Roles · comments · audit log

Webhooks

Git hooks

Event-driven HTTP

Cost

Free · self-hosted

The mental model

UPG works like Git

Both servers cost nothing to run. The local server reads a file on your disk; the cloud server runs on your own Postgres. Open spec, no lock-in either way.

Git

Local version control

Runs on · Your machine

UPG Local

Local graph queries

Runs on · Your machine

UPG Cloud

Multi-product graph DB

Runs on · Your infra (Docker)

One file, every surface

Your graph, everywhere

The same .upg file powers every surface. Every one speaks UPG.

VS Code ExtensionComing soon

Browse your graph in the sidebar: entity tree, overview, detail panels.

Desktop AppPlanned

The local graph in a native shell, offline-first with a dock icon.

Mobile CompanionPlanned

Capture ideas on the go. Voice-to-graph, quick entity creation.

View source on GitHub →Read the spec →Build an adapter →MIT licensed · free to self-host