Stellar Raven documentation

How Raven works, how to connect, and how to fix problems

What Raven is

Stellar Raven is a remote Model Context Protocol (MCP) server that gives AI agents Stellar documentation and ecosystem context through one connection.

Raven exposes exactly two tools over a single catalog of 60 operations, 19 skills, and 173 sections. One browser sign-in covers everything; you never handle API keys for the underlying services.

Connect your agent

Add https://raven.stellar.org/mcp to any MCP client that supports streamable HTTP and OAuth — Claude Desktop, Claude Code, Cursor, Codex, VS Code, and others.

The client starts an OAuth sign-in in your browser. Sign in once and approve the connection.
Access tokens last 1 hour; compatible clients refresh them automatically within a fixed 90-day authorization window before you sign in again.
No per-service keys are ever issued to your agent. All upstream service credentials stay on Raven's server.

The two tools

search ranks exposed operations and whole skills against your question. Operation hits carry a ready-to-call TypeScript signature, and runnable-skill hits can carry one too. Skill hits list their availableSections instead — individual skill sections are not searchable, so your agent reads them by exact section id. execute takes that shortlist and runs one JavaScript script inside a sandboxed isolate with no network access. Service operations run through host-side adapters that hold the upstream credentials and enforce policy. The eight allowed codemode helpers (codemode.spec, codemode.search, codemode.catalog, codemode.describe, codemode.skill.read, codemode.skill.run, codemode.artifact.info, and codemode.artifact.read) are functions on one host provider, inside the same sandbox boundary. This is the working loop:

1 · search ranks the catalog

search({ query: "soroswap liquidity", limit: 3 })
→ ranked hits with TypeScript signatures:
  scout.searchProjects · scout.searchResearch · stellarDocs.search_protocol_concepts_docs

2 · execute composes them in one script

const found = await scout.searchProjects({ q: "soroswap" });
if (!found.ok) return found.error;   // check r.ok first
if (found.data.projects.length === 0)    // ok:true can still be empty
  return { note: "no matches" };
const top = found.data.projects[0];       // payloads live under .data
return await scout.searchResearch({ q: `${top.name} liquidity` });  // composition

Every service call resolves to { ok: true, data } or { ok: false, error }. It never throws across the tool boundary.

The four source families

Each family answers different questions, and Raven's guidance tells your agent which to trust:

Lumenloop (lumenloop.*) — community and editorial ecosystem intelligence: project directory details, published research, content, audio/video passages, and SCF funding context.
Scout (scout.*) — the live ecosystem graph: projects, repos, builders, partners, hackathons, audits, and stablecoins.
Stellar Docs (stellarDocs.*) — official Stellar documentation. The authority for protocol behavior, standards status, and API shapes.
Skills (skills.*) — pinned operational playbooks read section by section: tested build, integration, security, and data procedures.

Ecosystem facts start with Lumenloop or Scout. Protocol and standards claims stay unverified until official docs confirm them.

Troubleshooting

Read the envelope first. Every service call resolves to { ok: true, data } or { ok: false, error }. Payload fields live under .data — read r.data.projects, never r.projects. codemode.skill.run, codemode.artifact.info, and codemode.artifact.read use that same envelope. The discovery helpers answer at the top level instead: codemode.search gives r.hits, codemode.describe gives entry fields such as r.signature and r.inputSchema, codemode.skill.read(id) gives r.content, and codemode.skill.read(id, { sections }) gives r.sections.
An empty answer may not be an answer. An error.kind of "error" means the call failed. A kind of "soft-empty" means the service answered with nothing — that is inconclusive, not proof something does not exist. Widen the search across families before concluding a negative.
Big results get truncated. Output is capped near the model's context budget. When a truncated response reports an available artifact, read the full payload back inside execute with codemode.artifact.read(id), then return only the fields you need. Artifacts expire after seven days, are stored only for signed-in MCP clients — API-key and Playground calls get none — and payloads above 2 MiB skip storage. When no artifact is reported, inspect the operation's signature before using arguments like limit or fields — only some operations accept them. The general fallback is to project the result in JavaScript — return just the fields you need — or split the script into smaller calls.
Service health. Check /health for the service heartbeat and /health/skills for playbook availability. Both are public and need no sign-in.
Sign-in fails or loops. The sign-in happens in your browser through WorkOS AuthKit; approve the Terms acknowledgement checkbox on the consent screen. After 90 days your client must send you through sign-in again — this is expected. If a client cannot complete OAuth at all, ask the operator for a named API key and send Authorization: Bearer name:token instead.

Get help

Ask in #raven in the Stellar Developers Discord. That channel is the support channel for Raven. Use it for connection problems, catalog questions, and failures this page does not resolve.

Report a security vulnerability privately instead: use GitHub private vulnerability reporting on stellar-experimental/stellar-raven, or email frontier@stellar.org. Do not post a vulnerability in Discord.