Quickstart

RCP ships four native SDKs that speak the identical wire format: a header-only C++ SDK and dependency-free Python, Node.js, and Rust SDKs. This page takes you from zero to a working retrieval engine in two steps:

1. See it run

Clone the repo and query the reference engine. Real output in under a minute.

2. Write your own

A complete, copy-paste engine you can run and then make real.

You only need Python 3 or Node.js installed — the reference engine is a toy in-memory index with no models, no vector database, and no network calls. It exists to show the protocol, not the retrieval math.

See it run

The repo ships a complete example server (a tiny retrieval engine) and a client that drives it. Running the client spawns the server, performs the initialize handshake, discovers the server’s capabilities, and calls three of them — all over plain JSON-RPC on stdio.

Clone the repo

git clone https://github.com/1ay1/rcp.git
cd rcp

Run the example client

python3 examples/example_client.py

node sdk/node/examples/example_client.js

Read the output

connected to rcp-example v1.0.0 (RCP/1)
capabilities: ['embed', 'retrieve', 'graph']
embed      -> 1 vector(s), dim=384
retrieve   ->
   d1  score=0.248  The Eiffel Tower is a wrought-iron lattice tower
   d2  score=0.135  Photosynthesis converts light energy into chemic
graph      -> {'summary': 'a global community summary would go here', 'communities': 1}

That is a full RCP session. The client never imported the server’s code — it only spoke the protocol. Swap the server for one backed by real embeddings and the client wouldn’t change a line.

Write your own engine

An RCP server is just a program that advertises what it can do and answers method calls. Here is a complete engine backed by a three-document keyword index. It runs as-is; replace the body of search with real vector search and nothing else changes.

Python
Node.js

Save the engine as my_engine.py

import re
import rcp

# A toy index: three documents ranked by keyword overlap.
# Swap `search` for real vector search — the wire contract never changes.
DOCS = [
    ("d1", "The Eiffel Tower is a wrought-iron tower in Paris, France."),
    ("d2", "Photosynthesis converts light into chemical energy in plants."),
    ("d3", "Mount Everest is Earth's highest mountain above sea level."),
]

def toks(text):
    return set(re.findall(r"[a-z0-9]+", text.lower()))

def search(query, k):
    q = toks(query)
    ranked = sorted(DOCS, key=lambda d: len(q & toks(d[1])), reverse=True)
    return [
        {"id": doc_id, "score": float(len(q & toks(text))), "text": text}
        for doc_id, text in ranked[:k]
        if q & toks(text)
    ]

s = rcp.Server()
s.set_info("my-engine", "1.0")
s.advertise(rcp.Capability.Retrieve, {"maxK": 100, "modes": ["hybrid"]})

@s.on(rcp.Method.RETRIEVE)
def _(params):
    return {"hits": search(params["query"], params.get("k", 10))}

s.serve_stdio()

Save a client as query.py

import rcp

c = rcp.connect_stdio(["python3", "my_engine.py"])
for h in c.retrieve("eiffel tower paris", k=3):
    print(h["id"], round(h["score"]), h["text"])

Run it

Install the SDK, then run the client (it launches the engine as a subprocess):

pip install rcp-protocol
python3 query.py

d1 3 The Eiffel Tower is a wrought-iron tower in Paris, France.

Save the engine as my_engine.mjs

import * as rcp from "rcp-protocol";

// A toy index: three documents ranked by keyword overlap.
// Swap `search` for real vector search — the wire contract never changes.
const DOCS = [
  ["d1", "The Eiffel Tower is a wrought-iron tower in Paris, France."],
  ["d2", "Photosynthesis converts light into chemical energy in plants."],
  ["d3", "Mount Everest is Earth's highest mountain above sea level."],
];
const toks = (s) => new Set(s.toLowerCase().match(/[a-z0-9]+/g) ?? []);

function search(query, k) {
  const q = toks(query);
  return DOCS
    .map(([id, text]) => [[...toks(text)].filter((w) => q.has(w)).length, id, text])
    .filter(([n]) => n > 0)
    .sort((a, b) => b[0] - a[0])
    .slice(0, k)
    .map(([n, id, text]) => ({ id, score: n, text }));
}

const s = new rcp.Server();
s.setInfo("my-engine", "1.0");
s.advertise(rcp.Capability.Retrieve, { maxK: 100, modes: ["hybrid"] });
s.on(rcp.Method.RETRIEVE, (params) => ({ hits: search(params.query, params.k ?? 10) }));
await s.serveStdio();

Save a client as query.mjs

import * as rcp from "rcp-protocol";

const c = await rcp.connectStdio(["node", "my_engine.mjs"]);
for (const h of await c.retrieve("eiffel tower paris", 3))
  console.log(h.id, h.score, h.text);
await c.shutdown();

Run it

Install the SDK, then run the client (it launches the engine as a subprocess):

npm install rcp-protocol
node query.mjs

d1 3 The Eiffel Tower is a wrought-iron tower in Paris, France.

Rust and C++ follow the identical shape — Server::new(), advertise a capability, register a handler, serve_stdio(). Complete, compiler-verified engines live at sdk/rust/examples/example_server.rs and sdk/cpp/examples/example_server.cpp; the Rust and C++ SDK pages walk through them.

Go further — two runnable demos

Once the basics click, two self-contained programs show off the parts of RCP that sell it. Both run with only Python 3, no models, no config:

Streaming (HTTP + SSE)

python3 examples/example_streaming.py

A real HTTP server streams notifications/progress frames as a 3-stage retrieve funnel fills, then the final response — over one SSE connection.

Federation (fan out + fuse)

python3 examples/example_federation.py

One command spawns two independent engines, fans a query out, and fuses their rankings with rcp.rrf_fuse — origin tags and per-engine weights.

What just happened

Every RCP session is the same three beats, in every language:

Initialize

The client connects and sends initialize. The server replies with the negotiated protocol version, its name, and its capabilities — the exact set of things it can do. See Initialization.

Gate on capabilities

The client checks a capability (c.supports(...)) before calling a method. Calling an unadvertised capability fails client-side, before any I/O — no wasted round trip. See Capabilities.

Call methods

The client calls capability-gated methods like retrieve and reads back normalized hits. The server ran whatever pipeline it wanted behind that one call. See the retrieval pipeline.

Notice what the client didn’t do: it didn’t know the server’s language, its index, or its ranking math. It only spoke the wire. That decoupling is the whole point — read Why RCP for the motivation.

Installing the SDK

The SDKs are published to their registries — install the one you need:

pip install rcp-protocol          # imports as `import rcp`

npm install rcp-protocol

cargo add rcp-protocol             # crate is `rcp`

# header-only, C++23 — via CMake:
#   find_package(rcp CONFIG REQUIRED)
#   target_link_libraries(app PRIVATE rcp::rcp)

Each SDK page has the full install and API details.

Where to go next

The method set

Every method at a glance, and the capability that gates it.

Core concepts

The wire format, capabilities, and errors — one concept per page.

Federation & Selector

Target one engine or fuse many from a single registry.

SDKs

The full API of each native SDK.

Get Started

Core Concepts

Methods

Features

Operating a Server

1. See it run

2. Write your own

See it run

Write your own engine

Go further — two runnable demos

Streaming (HTTP + SSE)

Federation (fan out + fuse)

What just happened

Installing the SDK

Where to go next

The method set

Core concepts

Federation & Selector

SDKs

1. See it run

2. Write your own

​See it run

​Write your own engine

​Go further — two runnable demos

Streaming (HTTP + SSE)

Federation (fan out + fuse)

​What just happened

​Installing the SDK

​Where to go next

The method set

Core concepts

Federation & Selector

SDKs

See it run

Write your own engine

Go further — two runnable demos

What just happened

Installing the SDK

Where to go next