Frequently Asked Questions

How does DGP compare to MCP (Model Context Protocol)? Updated Feb 2026

MCP is a universal transport—Claude Desktop, Claude Code, Cursor, Codex, and dozens of clients speak it natively. DGP is a domain protocol that rides on top of MCP. A DGP gateway exposes itself as an MCP server with three tools (schema, query, mutation), so agents don't need a new client.

The real difference is what happens inside those tools. MCP tools are isolated—each one is a standalone function with no awareness of the others. DGP tools share a domain graph with relationships, state machines, and orchestrated mutations that roll back on failure.

Dimension	MCP	DGP (over MCP)
Data model	Flat tool catalog	Semantic graph with typed relationships
Queries	One tool call per resource	Relationship traversal in a single call
Actions	Single-step, fire-and-forget	Orchestrated multi-step with rollback
Discovery	Tool list with defer_loading	Compressed schema (800 tokens) with semantic search
State machines	Not built-in	Entity lifecycles declared in schema
Transaction semantics	None—if step 3 fails, steps 1-2 persist	Declared compensation—gateway rolls back
Ecosystem	Ubiquitous—runs everywhere	Speaks MCP on the wire—runs everywhere too

What about Programmatic Tool Calling?

Anthropic's Programmatic Tool Calling (PTC) lets Claude write Python code to orchestrate tools, with only final results entering context. This is powerful for MCP workflows and actually complements DGP well:

• DGP queries return structured data — perfect for Python processing
• PTC can filter/aggregate DGP results before they enter Claude's context
• Multiple DGP queries can run in a single PTC code block

Example: Fetch 100 customers via DGP, process in Python, return only the 5 with overdue commitments. Claude sees 5 records, not 100.

How does DGP compare to GraphQL?

At the query level, the overlap is real. Entity, filter, traverse relationships, return shaped data—that's GraphQL's core competency and DGP does the same thing. The differences aren't in the query model. They're in what the protocol assumes about its consumer.

GraphQL assumes a human developer wrote the query. The schema is designed for IDE autocomplete, introspection is optimized for tooling like GraphiQL, and the type system is rich because a person will read it. An agent can use GraphQL, but it has to already know what it's looking for.

DGP assumes an agent is discovering the domain at runtime. The schema isn't just types—it's entities with state machines, relationships with cardinality semantics, and operations with declared side effects and rollback behavior. CSN exists because an agent needs to ingest a domain model in 800 tokens, not browse it in a UI. Discovery exists because the agent doesn't know what it's looking for yet.

The other real difference is mutations. GraphQL mutations are single operations—the client choreographs multi-step workflows. DGP mutations are orchestrated: "create a Pages site with DNS and Access protection" is one operation with declared compensation. The gateway owns the transaction semantics. That matters for agents because they shouldn't be managing rollback logic across API calls.

Dimension	GraphQL	DGP
Primary consumer	Human developers building UIs	AI agents discovering and querying domains
Schema purpose	IDE autocomplete, type safety	Runtime domain understanding in 800 tokens
Discovery	Introspection (assumes you know what to ask)	Semantic search ("help me protect this site")
Mutations	Single operations; client choreographs workflows	Orchestrated multi-step with rollback/compensation
State machines	Not built-in	Entity lifecycles declared in schema
Cost awareness	Not built-in	Every response includes token usage and cost
Provenance	Not built-in	Every response includes data lineage

When to choose GraphQL: You're building a traditional web or mobile app where developers craft queries by hand.

When to choose DGP: You're building agent systems that need to discover domains at runtime, traverse relationships without prior knowledge, and execute multi-step operations with transaction guarantees.

How does DGP compare to REST APIs?

REST is resource-oriented; DGP is domain-oriented. Key differences:

Dimension	REST	DGP
Data model	Resources at URLs	Atoms in a graph
Relationships	Links or nested resources (N+1 problem)	First-class edges, single query traversal
Filtering	Query parameters (inconsistent across APIs)	Standardized semantic filtering
Discovery	OpenAPI/Swagger docs	Queryable capability graph + llms.txt

Why should agents prefer DGP over REST?

Three reasons:

1. Cost transparency: Agents operating under budget constraints need to know what queries cost before executing them. DGP includes cost estimates in schema discovery and actual costs in responses.
2. Semantic discovery: Instead of parsing OpenAPI specs, agents can search for capabilities by description: "find operations that create calendar events."
3. Relationship traversal: A single DGP query can traverse multiple relationships without N+1 round trips.

What is CSN (Compressed Schema Notation)?

CSN is a token-efficient format for representing DGP schemas. While Tool Search with defer_loading reduces tool schema overhead, CSN serves a different purpose: domain understanding.

CSN provides the semantic context that lets agents reason about your business—relationships, constraints, state machines—not just call your tools.

Example: A Customer entity with computed fields and relationships might be ~3500 tokens in JSON Schema but only ~900 tokens in CSN. This matters when your context window is your constraint.

CSN is designed to be parseable by both humans and LLMs. It's not a query language — it's a schema representation format.

What's the relationship between DGP and AKG?

DGP is the query protocol; AKG is the data model.

AKG (Atomic Knowledge Graph) defines 23 atom types organized across five AEONS domains. These atoms — ToolAtom, SkillAtom, TaskAtom, etc. — are what DGP queries operate on.

You can use DGP without AKG (it works with any graph-shaped data), but DGP is specifically optimized for AKG's atom types and relationship patterns.

How does cost transparency work?

Every DGP response includes a cost object:

{
  "cost": {
    "tokens_input": 1250,
    "tokens_output": 3400,
    "usd": 0.0047,
    "breakdown": {
      "query_parse": 0.0002,
      "retrieval": 0.0015,
      "llm_calls": 0.003
    }
  }
}

Agents can use this to optimize subsequent queries, stay within budget caps, and report costs to users.

Does DGP replace MCP?

No. DGP rides on MCP—a DGP gateway is an MCP server. Agents connect using any MCP client and get three tools: schema, query, mutation. No new client library, no new transport.

Where DGP goes beyond MCP is inside those tools: relationship traversal, orchestrated multi-step mutations with rollback, state machines, and compressed domain discovery. For single-step fire-and-forget actions like send_email, a plain MCP tool is fine—DGP's mutation model adds overhead you don't need. For anything that touches multiple entities or crosses service boundaries, DGP mutations are the right tool.

What databases can DGP query?

DGP is backend-agnostic. The reference implementation includes adapters for:

• PostgreSQL (with graph-like queries via CTEs)
• Neo4j
• FalkorDB
• SurrealDB
• Redis (for caching layers)
• Mock adapter (for testing)
• Generic REST API adapter

Writing a new adapter requires implementing the DGPAdapter interface — typically 200-500 lines of code depending on the backend.

How do I expose an existing API via DGP?

Three approaches, from simplest to most integrated:

1. REST adapter: Point DGP at your OpenAPI spec; it generates a queryable schema automatically. Limited relationship traversal.
2. Schema mapping: Define a DGP schema that maps to your existing endpoints. Full DGP features, your backend unchanged.
3. Native integration: Implement a custom adapter that translates DGP queries to your backend's native query language. Best performance.

How do I connect an MCP client to a DGP gateway?

A DGP gateway is an MCP server. Point any MCP client at the gateway URL over Streamable HTTP. No local process, no bridge layer, no client-specific code.

The configuration is the same across clients—Claude Desktop, Claude Code, Cursor, Codex, Windsurf:

// MCP client config (same for all clients)
{
  "mcpServers": {
    "cloudflare-dgp": {
      "type": "http",
      "url": "https://your-gateway.workers.dev/mcp",
      "headers": {
        "X-Gateway-Key": "your-secret"
      }
    }
  }
}

The agent calls schema to discover the domain (~800 tokens), then query and mutation to interact with it. The gateway handles relationship traversal, orchestrated mutations with rollback, and authentication—the agent just speaks MCP.

What's in the Python implementation?

The dgp-python package includes:

• Query builder with fluent API
• Schema loader and validator
• Production-ready gateway with rate limiting, circuit breakers, and caching
• Prometheus metrics
• Async support throughout
• 1048 tests across all features

pip install dgp-python

How does DGP fit with AFP and ZKA?

These protocols handle different communication patterns:

• DGP: Agent ↔ Database (vertical) — querying and mutating domain data
• AFP: Agent ↔ Agent (horizontal) — cross-agent collaboration and task delegation
• ZKA: Agent ↔ Agent (economic) — privacy-preserving payments and proofs

An agent might use DGP to query its local knowledge graph, AFP to delegate a subtask to another agent, and ZKA to pay for that agent's services — all in a single workflow.

How does DGP fit with MCP?

MCP is the transport layer. DGP is the domain protocol. A DGP gateway exposes itself as an MCP server — agents connect the same way they connect to any other MCP tool. The difference is what they get: not isolated functions, but a traversable domain graph with orchestrated mutations, state machines, and compressed schema discovery.

An agent can mix DGP and plain MCP tools in the same workflow. Use DGP to query customers with overdue commitments, a plain MCP tool to send reminder emails, and a DGP mutation to mark commitments as reminded — with rollback if the state update fails.

Who maintains DGP?

DGP is developed by Pyramidal and released under the MIT license. The protocol is designed to be adopted independently of Pyramidal's commercial products.

How can I contribute?

Open an issue or pull request on the GitHub repository. For significant changes, we recommend opening a discussion first.