Selda MCP

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.

What you can do with it

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.

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.

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.

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":"etunimi@filterit.fi",
        "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

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:

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.