Selda

Connect an AI client to a Selda workspace.

Others give you a list. Selda gets you the conversation: you say who you want, and it finds the right people, writes each message from real research, and carries the thread to a customer, a quote, or a meeting. 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.

What you can do with it

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
Clear the rows a trial install left behind	selda_delete_lead, or selda_merge_leads for a duplicate

What you cannot do with it, on purpose

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.

Connect

OAuth, recommended for Claude.ai, ChatGPT and Cursor

Add this as a custom connector:

https://mcp.selda.ai/api/mcp

The server advertises OAuth, so the client walks you through logging in and picking a workspace. Nothing to paste.

A static key, for Claude Code, scripts and CI

Create a key in the Selda app under Settings → Connections → MCP server. The full key is shown once.

claude mcp add --transport http selda https://mcp.selda.ai/api/mcp \
  --header "Authorization: Bearer $SELDA_API_KEY"

Any other MCP client that reads a config file takes the same URL and the same header.

Keys, scopes and isolation

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 HTTP API underneath

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.

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.

Grounding a message on research you already have

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:

curl -X POST "$SELDA_API_BASE/mcp/mutate" \
  -H "Authorization: Bearer $SELDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fn":"leads.add","args":{
        "projectId":"<workspace id>",
        "company":"Filterit Oy",
        "email":"[email protected]",
        "analysis":"They run three production lines and posted about downtime in March..."
      }}'

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.

Repository contents

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.

What a sandbox key can and cannot do

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.

Support

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.