The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Selda listing page.
Connect an AI client to a Selda workspace.
Others sell you a tool. Selda builds your sales machine: it watches for the moment worth reaching out, researches each company, writes the message in your customer's language, sends it from your own inbox and brings the reply back to you. A person approves every send. This repository is the machine readable documentation for driving that engine from outside the app, over the Model Context Protocol or plain HTTP.
MCP and the API are on every plan, the free one included. There is no tier to reach before you can connect a client — see Keys, scopes and isolation for what a key on a free workspace can do.
The narrative documentation lives at docs.selda.ai/reference/mcp. When the two disagree, the live capability manifest described below is right.
| You want to | How |
|---|---|
| Read your workspaces, leads, campaigns and threads from an AI client | Connect the hosted server, then just ask |
| Push research you already did into Selda so it writes from your material | selda_add_lead with an analysis field, or upload files and import them |
| Run the full pipeline from a brief and read the drafts it produced | selda_run_pipeline, then poll selda_get_run_status |
| Receive replies as they arrive instead of polling | Register an outbound webhook for reply.received |
| Have an arriving enquiry answered before anyone looks at it | selda_ingest_event with autoAdvance, then listen for draft.ready |
| Put a picture in a message, a different one per lead | mediaImageUrl on selda_add_lead / selda_add_leads / selda_ingest_event, with mediaLinkUrl to make it clickable |
| Send a file with a message, or with every message in a campaign | selda_upload_file, then selda_attach_files with a leadId or a runId |
| Clear the rows a trial install left behind | selda_delete_lead, or selda_merge_leads for a duplicate |
Nothing here sends outreach. A script can build a campaign all the way up to drafted messages. A human presses send, in the Selda app. There is no function that launches a campaign's sends, and there is no flag that turns that off.
This is not a limitation we plan to remove. It is the product's central claim: Selda recommends, the human decides.
Add this as a custom connector:
The server advertises OAuth, so the client walks you through logging in and picking a workspace. Nothing to paste.
Create a key in the Selda app under Settings → Connections → MCP server. The full key is shown once.
Any other MCP client that reads a config file takes the same URL and the same header.
A key is sk_live_… (live) or sk_test_… (sandbox). Only a SHA-256 hash of it is ever stored, so
a lost key is revoked, never recovered.
| Scope | Grants |
|---|---|
read | read operations |
write | write operations |
pipeline | pipeline and engine actions, which cost credits |
Every call is bound to the organization that owns the key. The org id is injected server side from
the validated key and an orgId in your request body is ignored. One organization's key cannot
reach another organization's data.
Every plan can connect, the free one included. Creating a key is not gated on a tier or an
invoice. A workspace standing in test mode always mints sk_test_; a workspace approved for live
always mints sk_live_. The prefix states the environment and grants nothing on its own — every
gate reads the stored environment and the workspace's live entitlements, re-resolved on each
request.
So on a free workspace you get a test key that reaches the whole surface except the handful of functions that spend money or resolve real people. That is enough to build the entire integration before anything is real. The capability manifest is the authority on which functions a given key may call.
The MCP tools are a curated front end over an HTTP API you can call directly.
The base is https://api.selda.ai.
| Endpoint | Method | Purpose |
|---|---|---|
/mcp/query | POST | reads |
/mcp/mutate | POST | writes |
/mcp/run | POST | pipeline and engine actions |
/mcp/material/upload | POST | raw file bytes in, a storage id out |
/mcp/capabilities | GET | the capability manifest, no key needed |
Every one of these also answers on a /v1/ alias — /v1/mcp/query, /v1/mcp/mutate,
/v1/mcp/run, /v1/mcp/material/upload, /v1/mcp/capabilities — pointing at the same handler.
The unversioned paths are kept for good and will not break; /v1/ is the seam where anything that
changes behaviour would appear, so prefer it in something long-lived.
The body is always { "fn": "...", "args": { ... } }. A success is { "value": … }; a failure is
{ "error": { "type", "code", "message", "request_id" } } with a non-200 status.
There is also a URL per operation, if that is what your client wants: GET /v1/leads,
POST /v1/leads, POST /v1/runs/{runId}/confirm-companies and sixty-odd more, with an OpenAPI 3.1
document. Same dispatcher, same key check, same scope check, same refusals, so neither form can
reach what the other declines. That surface is documented in
Selda-rest-api. Use it when you are writing code;
use this repository when you are connecting an AI client.
Discover the base URL and the current function list from the manifest rather than hardcoding
either. See examples/ for a client that does exactly that in about forty lines.
You probably already produce per-prospect research somewhere else. Two ways to bring it in, and both make Selda write from your material instead of crawling from scratch.
One company you already researched:
A folder of files, one folder per company: upload each file with an X-Selda-Path header, then
import the returned storage ids. The leading folder in the path is how Selda maps a file to a
company, so boreo/filterit/analyysi.pdf belongs to Filterit.
Importing material creates the campaign and the company list and stops there. Giving Selda your
material is permission to read it, not permission to run a campaign. An autoAdvance argument lets
a script grant the next stages one at a time, and even then it cannot send.
| Path | What it is |
|---|---|
schemas/capabilities.json | Every function, generated from the live service |
examples/ | A minimal working client, no dependencies |
skills/ | Loadable skills that teach an AI client how to use Selda well |
CHANGELOG.md | Changes to the tool surface, so an integration does not break silently |
schemas/capabilities.json is generated from GET /mcp/capabilities, which is itself derived from
the same dispatch tables the endpoints run on. It cannot describe a function that does not exist,
and it cannot omit one that does. Each entry carries its fn, endpoint, scope, one-line summary,
the MCP tools that wrap it, whether a sandbox key may call it, why not when it may not, and any
extra entitlement it needs.
If the file and the live endpoint ever disagree, the endpoint is right and this repository is stale. Fetch it yourself in anything long-lived.
Of the 72 functions the manifest published on 30.8.2026, 65 were open to a sandbox key and 7
were not. Those figures move whenever the surface does, so read them off
GET /mcp/capabilities rather than off this paragraph — the manifest is authoritative and this
number is a snapshot.
The line is not "reads versus writes". A sandbox key can read the whole workspace and push your own data in: add leads with your own research, write the Brain, upload material, import it, draft against it. That is the whole product in test mode, and it is how you build something worth paying for before you pay.
What a sandbox key cannot do is make the engine produce new contact data or reach a real person:
| Function | Why it costs |
|---|---|
company.lookup | resolves real people through paid data providers |
leads.enrich, leads.enrichBatch | same, per lead |
engine.start | discovery: web search, crawls, per-lead spend |
connectors.sync | pulls and enriches from an outside source |
runs.confirmCompanies | confirms a run's company list, which starts the paid work |
runs.startFromLeads | writes a message per lead you pushed in |
material.import with autoAdvance | the grant carries the run into contact lookup |
The question these ask is who pays, not which prefix you hold. A sandbox key belonging to a
workspace that already has the API on its plan, with its invoice paid, may call every row above and
spends that workspace's own credits doing it. The refusal is aimed at a free account scripting
Selda into a contact-data API at Selda's expense — not at a paying customer working in a sandbox.
material.import is the one row that is conditional on its arguments rather than on the function,
so it reports sandboxAllowed: true in the manifest and refuses only when autoAdvance is passed.
This table listed messages.send until 20.8.2026. No such function exists in any dispatch table
and none is planned — a live key buys the calls above, which spend money or reach a data provider,
never the one that reaches a recipient. The line is corrected here rather than quietly deleted,
because anyone who read it may have planned around it.
A refused call returns 403 with a code you can branch on and a sentence you can show a person.
Creating a workspace is not on either list: it happens in the Selda app, and there is no function
for it by any key.
Questions, or a tool you need that does not exist: docs.selda.ai/support.
MIT licensed. This repository contains documentation, examples and skills. It does not contain Selda's source code.