Blueprint Nexus Developer API & MCP Server

Blueprint Nexus (blueSC) exposes the same knowledge graph its own workspace UI runs on: a Model Context Protocol server for AI agents, a JSON-RPC tool API, and a published OpenAPI 3.1 description. Query workspaces, traverse the graph, create nodes, link concepts, and ingest documents from Claude Desktop, Cursor, ChatGPT Custom GPTs, LangChain, LlamaIndex, or any HTTP client.

Discovery Endpoints

Fetch these first

II.

When to use the Blueprint Nexus API

Reach for this API when an agent or service needs durable, connected context rather than a one-off answer: grounding a chat assistant in a workspace's own notes, tasks, decisions, and dependencies; writing research or telemetry back into the graph; or traversing relationships to answer multi-hop questions such as what depends on what.

It is the wrong tool for general-purpose text generation — the graph stores and retrieves your knowledge, and the models you already use reason over it.

Ground an assistant in a workspace: read nodes, documents, and their edges so answers cite real context.
Write back as you work: create nodes, link concepts, and ingest documents so the graph stays current.
Traverse dependencies: walk edges to find upstream/downstream effects before a change.
Record governance: log decisions, proposals, and telemetry into an auditable trail.
Automate a workspace: script the same operations the workspace UI performs.

III.

Authentication

Every MCP and REST call authenticates with a workspace API key sent as `Authorization: Bearer <key>`. Keys are created inside the workspace (the `/api/mcp/keys` endpoint does the same thing programmatically) and are scoped to a single workspace with explicit scopes such as `bkn:read`, `bkn:write`, `bkn:ingest`, and `mcp:tools`.

Keys are never stored in the clear: the server keeps a SHA-256 hash and validates a presented key against it, then resolves the workspace from the key record. Database access is tenant-isolated by PostgreSQL Row-Level Security, so a key can only ever reach the workspace it belongs to. Treat a key as a password: send it over HTTPS only, keep it in an environment variable, and revoke it with `DELETE /api/mcp/keys` if it leaks.

Header: `Authorization: Bearer <workspace-api-key>` on every request.
Scope: one workspace per key — the workspace is derived from the key, not from the request body.
Missing or revoked key: `401` with a JSON-RPC `-32001` error on MCP endpoints.
Never expose a key in a browser bundle, a repository, or a query string.

IV.

MCP server

The Model Context Protocol server is the recommended integration path for AI agents: declare it once in your client and the tool list, schemas, and results are negotiated for you. Two transports are served — prefer Streamable HTTP for new clients, and use the SSE transport for clients that predate it.

POST/api/mcpRecommended
Streamable HTTP transport: send a JSON-RPC 2.0 request and get a JSON result back. Stateless — authenticate every request with a Bearer key.
GET/api/mcp/sse
HTTP+SSE transport: opens a stream whose first event (`endpoint`) advertises the messages URL to post into.
POST/api/mcp/messages
JSON-RPC 2.0 message endpoint used by the SSE transport. Also accepts a bare arguments object, which is wrapped into a `tools/call` for non-JSON-RPC clients.
POST/api/mcp/messages/{tool}
One URL per tool (for example `/api/mcp/messages/bkn_query_graph`) that takes the tool arguments directly — the shape ChatGPT Custom GPT Actions expects.
POST/api/mcp/ingest
Ingest unstructured text into a workspace and connect it to the graph.
GET, POST/api/mcp/connect
Inspect and establish an MCP client connection for a workspace.
GET, POST, DELETE/api/mcp/keys
List, create, and revoke workspace API keys. Session-authenticated (this is how you mint the Bearer key the other endpoints expect).
GET/api/mcp/openapi
Workspace-scoped OpenAPI 3.1 document with one expanded path per MCP tool. Requires a `workspace_id` query parameter.

Call a tool over Streamable HTTP

curl -sS https://www.bluesc.org/api/mcp \
  -H "Authorization: Bearer $BLUEPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "bkn_query_graph",
      "arguments": { "query": "launch roadmap", "limit": 5 }
    }
  }'

Open the SSE transport

curl -N https://www.bluesc.org/api/mcp/sse \
  -H "Authorization: Bearer $BLUEPRINT_API_KEY"

Available tools

Tool names, descriptions, and input schemas are the same ones the server advertises over MCP and lists in `/.well-known/mcp/server-card.json`.

MCP tools

Tool	Description
bkn_list_workspaces	List all available workspaces in Blueprint Nexus with their node counts, descriptions, and modification timestamps.
bkn_create_workspace	Create a new project workspace in Blueprint Nexus with automatic registration of ownership, workspace settings, documentation, and initial Knowledge Graph (BKN) nodes.
bkn_query_graph	Search and retrieve nodes and edges from the workspace Knowledge Graph (BKN). Returns nodes, properties, and typed relationships.
bkn_ingest_content	Universal Graph Ingestion engine. Analyzes raw unstructured text, application logs, specs, or code snippets, extracts entities and relationships, and automatically upserts them into the workspace Knowledge Graph.
bkn_create_node	Explicitly create or update a single Knowledge Node in the workspace Knowledge Graph.
bkn_link_nodes	Create a directed, typed edge between two existing nodes in the workspace Knowledge Graph.
bkn_get_workspace_context	Fetch comprehensive context about the workspace, including executive summary, tech spec, open user stories, tasks, and key Knowledge Graph nodes.
bkn_push_telemetry	Stream runtime telemetry, errors, or application events from an external app directly into the workspace's activity and audit log.
bkn_mutate_variable	Mutate a Variable Node (e.g. increment daily push-ups counter, toggle smart light switch, or reset state) in the workspace Knowledge Graph. Automatically evaluates and fires connected reactive edge triggers.
bkn_delete_node	Delete or archive a node in the workspace Knowledge Graph (BKN) and sever all connected relationships.
bkn_unlink_nodes	Delete a directed relationship (edge) between two nodes in the workspace Knowledge Graph.
bkn_get_subgraph	Retrieve nodes scoped to a parent_uuid (or root if omitted) for fractal subgraph exploration.
agent_traverse_node	Move an autonomous agent along a connected edge to a neighboring node, updating its topological location and streaming its traversal trail.
bkn_emit_signal	Emit an active graph signal onto a target node or the workspace, broadcasting across the graph and alerting resident agents.
bkn_resolve_signal	Mark an active graph signal as resolved, recording resolution notes and timestamps.
bkn_list_signals	List active and unacknowledged signals for the workspace or a specific node, ordered by severity.

VI.

REST and OpenAPI

The published specification at `/openapi.json` is an OpenAPI 3.1.0 document covering the public agent surface with operation IDs, typed parameters, response schemas, and the error envelope. Generate a client from it instead of hand-writing requests, and use it to discover endpoints programmatically.

Read the contract before you code

curl -sS https://www.bluesc.org/openapi.json | jq '.paths | keys'

# Workspace-scoped document with one path per MCP tool:
curl -sS "https://www.bluesc.org/api/mcp/openapi?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $BLUEPRINT_API_KEY"

VII.

Rate limits

Limits are enforced as sliding windows and reported on every API response so a client can throttle itself instead of discovering the ceiling through failures. When a limit is exhausted the API answers `429` with `Retry-After` in seconds.

Enforced limits

Bucket	Applies to	Limit	Scope
general	Request throttling shared by public IP-scoped endpoints	60 requests / 60 s	Per IP address
mcp	MCP tool execution on the messages endpoint	60 requests / 60 s	Per workspace API key
ai	Model-backed endpoints (planning, generation, vision)	30 requests / 60 s	Per caller
intel	Research, synthesis, and indexing jobs	15 requests / 60 s	Per caller
agent	Agent fleet execution ticks	10 requests / 60 s	Per caller

Rate-limit response headers

Header	Meaning
RateLimit-Limit	Requests permitted in the current window.
RateLimit-Remaining	Requests left in the current window.
RateLimit-Reset	Seconds until the window resets.
RateLimit-Policy	The enforced policy, e.g. `60;w=60` (requests; window seconds).
Retry-After	Seconds to wait before retrying. Sent on `429` responses.

A 429 answer, headers and body

HTTP/2 429
retry-after: 12
ratelimit-limit: 60
ratelimit-remaining: 0
ratelimit-reset: 12
content-type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "hint": "Wait for Retry-After seconds before retrying this request.",
    "docs": "/openapi.json"
  }
}

VIII.

Errors

HTTP endpoints answer JSON, never an HTML error page. Every failure carries a stable machine `code`, a human `message`, a `hint` describing how to recover, and a `docs` pointer at the specification. MCP endpoints answer JSON-RPC 2.0 error objects instead (`-32001` for auth, `-32601` for an unknown tool, `-32029` for rate limits).

Structured HTTP error

{
  "error": {
    "code": "not_found",
    "message": "Unknown API path: /api/v1/nodes",
    "hint": "Read /openapi.json for the public endpoint list.",
    "docs": "/openapi.json"
  }
}

IX.

CLI and client library

The MCP package published from this repository ships two binaries: `blueprint-cli`, a tool runner for scripting and smoke-testing calls, and `blueprint-nexus-mcp`, a stdio server that proxies JSON-RPC to the hosted endpoint so a desktop agent client can connect without a network listener.

Run a tool or start the MCP client from the terminal

# Tool runner (published from this repository as @blueprint-nexus/mcp-server)
npx --package @blueprint-nexus/mcp-server blueprint-cli bkn_query_graph '{"query":"launch roadmap","limit":5}'

# stdio MCP server for Claude Desktop, Cursor, or any MCP client
npx --package @blueprint-nexus/mcp-server blueprint-nexus-mcp --key $BLUEPRINT_API_KEY

Interactive Runtime

Explore the workspace itself

The graph these endpoints expose is the same one the product runs on. Try it without an account in the sandbox, or read the guides for the workspace, knowledge graph, and agent fleet.

Open the sandbox Read our blog & guides