Connect via MCP
Connect DarkPrint and your agent can search the registry by describing the task in its own words. It can then fetch a whole blueprint with the steps to instantiate it, read a card, inspect provenance, or fetch a release by digest.
1. Connect a client
Pick your client and run the command, or paste the JSON into its MCP settings. The server is remote, so there is nothing to install and nothing to keep updated.
claude mcp add --transport http darkprint https://www.darkprint.io/api/mcpOne command in the terminal. Claude Code connects over HTTP and installs nothing.
Client docs ↗The same server also runs on your own machine over stdio, as npx -y darkprint mcp, for a client that cannot reach the remote address above.
The server can only read. Without a key every call reads as anonymous and sees public blueprints and cards only; a key from Settings, sent as a bearer token, raises the rate limit and lets the four addressed tools reach your own private blueprints. Nothing here runs a blueprint.
2. The tools
Seven tools. Two search by task, one returns a whole blueprint, three read one thing by its address, and one compiles a release for Attractor. Each returns facts about a blueprint or a card and no judgement of it: what it is, who published it, and the digest it was published under.
| Tool | Takes | Returns | Status |
|---|---|---|---|
| find_blueprints | the task in prose, an optional limit (1 to 20, default 5), whether to include forks, and the structural filters phase, autonomy, gates and dark_factory | blueprints ranked best first, each with its ref, author, digest, title, summary, tags, score, similarity, evidence and a scorecard summary | live |
| find_cards | the task in prose and an optional limit | node cards ranked best first, one per card id, each with its ref, digest, name, type, action, phases, tools, risk markers, the blueprints that use it, score, similarity and evidence | live |
| get_blueprint | an owner handle and a slug; optionally an exact digest and a harness (claude-code, codex or generic) | the whole bundle in one answer: topology.dot, every card it pins under cards/, README.md, plus its manifest, scorecard, provenance and numbered steps for instantiating it | live |
| read_card | a card reference, written id@version | the card's YAML as published: what the node does, which phase it works in, its inputs and outputs, and what must never reach it | live |
| inspect_provenance | an owner handle and a blueprint slug | who published it, what it was forked from, and every release with its version and digest | live |
| fetch_release | an owner handle, a slug and an exact digest | the list of files in that exact release; each file is then fetched from /api/files by path, or all at once through get_blueprint | live |
| export_pipeline | an owner handle, a slug and an exact digest | that release compiled into a pipeline file for Attractor, the runner DarkPrint compiles to, with a header naming what a DarkPrint blueprint could not express in it | live |
The digest is what makes a result safe to depend on. Fetch by slug and you get whatever the registry holds today. Fetch by digest and you get the bytes you tested against, even after a newer release is cut.
export_pipeline is the one tool that is not a registry read. It takes the files of one release and compiles them into a pipeline for Attractor, which is what darkprint export <dir> --attractor does in a terminal. The file opens with a header listing what a DarkPrint blueprint cannot express in Attractor’s format. Some settings the runner fills in with its own defaults. Others a handler requires, and leaving one empty makes the run refuse rather than guess.
3. How to read the results
- order
Results come back ranked by how close each blueprint or card is to the task you described, best match first: the cosine similarity between your task and the document DarkPrint keeps for it, plus a small bonus for words that match. Each hit shows its score and lists every field a word matched, so you can check the order against the documents. The score is a similarity and says nothing about quality. When the vector channel is unavailable the response says encoder: absent and the order is word matches alone. The response also carries ordered, which reads false whenever any hit in the answer arrived without a similarity, so an agent knows when the positions are not comparable.
- what a hit contains
A find hit carries identifiers, a scorecard summary and the evidence, never a copy of the document. get_blueprint returns the whole bundle in one answer and read_card returns one card, each pinned to the version or digest you asked for, so nothing you act on is an unversioned excerpt.
- who is asking
With a key, get_blueprint, read_card, inspect_provenance and fetch_release reach your own private blueprints; the two find tools search public blueprints only. A key of either scope raises the rate limit, and none lets this server write anything.
- cards and releases
A card is pinned by its id and version. A release is pinned by its digest, a SHA-256 hash over the graph and the cards it pins, attribution aside. They are two different guarantees, and your agent asks for whichever one it needs.