Selda MCP Server

The Selda MCP server lets external AI tools (Claude Desktop, Claude Code, ChatGPT, or any Model Context Protocol client) drive a user’s Selda workspace: list projects, inspect leads and campaigns, read threads, and run the GTM pipeline. It is gated behind an API key. Every plan can connect with a test key (test mode, the full product, nothing sends for real); a live key requires a paid plan (Pro and up).

The Selda web app is at https://app.selda.ai.

Transport, in one answer

Read this first if you are writing an integration, because the rest of the page describes three things and you only need one of them.

Use https://mcp.selda.ai/api/mcp. It speaks MCP Streamable HTTP over POST, JSON-RPC 2.0 in the body. It is stateless: there is no session to establish, Mcp-Session-Id is neither required nor issued, and responses come back as plain JSON, never SSE. GET on the same URL returns a health object carrying the server version, which is the only thing here you can read without a key. DELETE is accepted and does nothing.

Protocol version. initialize echoes the version you asked for when it is one of 2025-06-18, 2025-03-26 or 2024-11-05, and answers with the newest otherwise. Nothing on this server is version-specific, so pick whichever your client speaks.

Authenticate either way:

• ?key=sk_live_... in the query string, or Authorization: Bearer sk_live_...
• or OAuth: the server publishes /.well-known/oauth-protected-resource, so Claude.ai, ChatGPT and Cursor can log you in with no key to paste

Connecting from ChatGPT works through the same URL and the same OAuth discovery. ChatGPT additionally requires a server to expose two tools named search and fetch, with fixed shapes; Selda serves both, and they are described under Tools.

If you are writing a script rather than connecting an AI client, skip MCP entirely and call the HTTP API directly: POST to the deployment’s .convex.site host with a body of { fn, args }. That is what both MCP servers do underneath, and it is simpler than speaking JSON-RPC.

The pieces

There are two MCP servers in front of one HTTP API, and their toolsets are not the same size: the hosted server serves every tool, the local stdio server serves a subset. The exact split is in the generated table under Tools. Unless you specifically need a local process, use the hosted one.

1. The hosted MCP server (recommended), https://mcp.selda.ai/api/mcp, implemented in api/mcp.ts, runs on Vercel Edge, speaks MCP Streamable HTTP, stateless. Connect it from Claude.ai (Add custom connector) or any remote-MCP client with https://mcp.selda.ai/api/mcp?key=sk_live_xxx. No local install.

2. The local Node MCP server, mcp-server/index.ts. A stdio MCP server spawned by the client (e.g. Claude Desktop via npx tsx) that forwards each tool call over HTTP to the same backend.

Both call the Convex HTTP endpoints, defined in convex/mcpApi.ts and routed in convex/http.ts:

Each also has an OPTIONS route for CORS preflight. The base URL is the deployment’s .convex.site host (prod default: https://brave-buzzard-349.eu-west-1.convex.site, overridable via SELDA_API_URL / VITE_CONVEX_SITE_URL).

The HTTP body is always { fn, args }, where fn is a registry key (e.g. projects.list) and the handler returns { value } on success or { error } with a non-200 status on failure.

Authentication & scoping

• API key format: sk_live_… (prefix + 40 random alphanumeric chars).
• Transport: sent as a Bearer token: Authorization: Bearer sk_live_…. The Node server reads it from the SELDA_API_KEY env var.
• Creation: keys are minted via apiKeys.createKey (called from the app UI: Settings → Apps → Selda MCP). The full plaintext key is returned once at creation and never stored or shown again.
• Storage: only a SHA-256 hash of the key (keyHash) plus a display keyPrefix (first 16 chars + ...) are persisted in the apiKeys table. The plaintext key is never written to the database.
• Validation: every HTTP call runs apiKeys.validateKey over the request’s hashed token. A key is rejected if it is missing/expired, revoked (revokedAt), the owning user is deleted/disabled, or the owning org no longer exists. On success it returns the key’s orgId, userId, and scopes.
• Revocation: apiKeys.revokeKey (UI) sets revokedAt; the key stops validating immediately.

Scopes

Default scopes for a newly created key are ["read", "write", "pipeline"]. The admin scope exists for internal cross-org tooling and is not granted through normal self-service key creation (security-hardened, see the internal security notes).

Org isolation

Each HTTP handler:

1. checks the required scope for that endpoint (e.g. /mcp/query requires read), returning 403 if missing;
2. injects the key’s orgId (and, where relevant, userId) server-side into the called function’s args.

Because the org id comes from the validated key, never from the request body, a key can only ever reach data belonging to its own organization. Every underlying mcpQueries.* function re-verifies org ownership (e.g. a lead is only returned if its project’s orgId matches the key’s org). One org’s key cannot read or mutate another org’s projects, leads, campaigns, or messages.

What you can actually do

The MCP tools below are a curated front end. Underneath, the HTTP API exposes the full registry, every fn you can pass to { fn, args }. If a tool doesn’t exist for what you want, the fn probably does. Reach for this list when you are writing a script rather than chatting with a client.

Every call is scoped to the API key’s organization. Never send orgId, it is injected server-side from the validated key, and a value in the body is ignored.

Push your own research in

You already produce per-prospect research somewhere else (a Claude Code pipeline, a scraper, a consultant’s PDFs). Two ways to get it in:

Folder shape is the mapping. The path you send in X-Selda-Path is how Selda knows which company a file belongs to. boreo/filterit/analyysi.pdf means “this belongs to Filterit”. Send the path relative to the folder you’d otherwise have dragged into the app.

# 1. One upload per file. Keep each returned storageId.
curl -X POST https://api.selda.ai/mcp/material/upload \
  -H "Authorization: Bearer $SELDA_API_KEY" \
  -H "X-Selda-Path: boreo/filterit/analyysi.pdf" \
  -H "Content-Type: application/pdf" \
  --data-binary @analyysi.pdf
# → { "value": { "storageId": "…", "path": "…", "sizeBytes": 20481 }, "request_id": "req_…" }
 
# 2. Turn them into one campaign.
curl -X POST https://api.selda.ai/mcp/run \
  -H "Authorization: Bearer $SELDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fn":"material.import","args":{
        "projectId":"<workspace id>",
        "files":[
          {"path":"boreo/filterit/analyysi.pdf","storageId":"…","sizeBytes":20481,"mimeType":"application/pdf"},
          {"path":"boreo/tornokone/tiedot.md","storageId":"…","sizeBytes":512,"mimeType":"text/markdown"}
        ]}}'

Optional args: assignments ([{ folderName, domain }] when you know a company’s domain and don’t want Selda guessing), excludedFolders, campaignName, autoAdvance.

The message structure

A campaign can carry a document that decides what its messages are made of. Without one, messages are written from the brief alone.

curl -X POST https://api.selda.ai/mcp/mutate \
  -H "Authorization: Bearer $SELDA_API_KEY" -H "Content-Type: application/json" \
  -d '{"fn":"campaigns.setMessageStructure","args":{
        "campaignId":"...",
        "blocks":[
          {"kind":"generated","role":"subject","aiInstruction":"Name the one thing you found on their site."},
          {"kind":"generated","role":"body","label":"Observation","aiInstruction":"State what you verified about them. One observation, plainly, no consequence clause."},
          {"kind":"locked","role":"body","label":"Offer","content":"Ensimmäinen vaihe on 380 euroa, alv 0 %. Jos työ ei ole valmis kahdessa viikossa, en laskuta."},
          {"kind":"generated","role":"body","label":"Ask","aiInstruction":"Ask whether the direction looks right. Never propose a meeting."}
        ],
        "form":{"paragraphs":6},
        "mustNever":["Never call it an audit","Never name another customer"]}}'

locked ships word for word. Nothing rewrites it, and the composer assembles around it. generated carries your instruction and Selda writes that part from real material. The one thing an instruction cannot do is make a claim true: where it asks for an observation the research does not establish, that part is left out rather than invented.

campaigns.lockMessageStructure with locked: true freezes the whole document; false takes it back to draft, because a lock the operator cannot undo is Selda refusing them their own document.

Neither call sends anything. A structure decides how a message is written; a person still approves every send in the app.

material.import creates the campaign and the company list and stops there. Pushing material is permission to read the material, not to run a campaign, the same rule as dropping a folder in the app. From there Selda proposes who to reach at each company, justified from what you sent, and a human accepts each one.

autoAdvance is how a script grants further stages, and it is per stage:

Neither form can send. Sending is launchRun behind human approval, and there is no fn for it.

Limits: 25 MB per file, and the same per-key rate limit as every other call. A projectId outside your key’s organization returns the same “no such workspace” error as one that doesn’t exist.

The full registry

Every function, one page each, with its endpoint, its scope, whether a free test key can call it, what it takes and an example request:

• API functions in the sidebar, one entry per fn with its endpoint badge
• Function reference for the whole list on one page

Those pages are GENERATED from convex/lib/mcpRegistry.ts, the same table these endpoints dispatch from, and a test fails if they drift from it. The tables that used to sit here were written by hand, and a hand-written copy of a registry is a copy that goes wrong in both directions at once: the API page it replaces listed nineteen functions that are in no registry and was missing thirty-nine that are.

The API also serves the list itself, no key needed:

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

The same list appears in the app under Settings, Integrations, MCP server.

Webhooks

The other half of the loop. Register an endpoint with webhooks.create and Selda POSTs to it, instead of you polling messages.byLead on a timer.

Events

What arrives

POST to your URL, Content-Type: application/json, with two headers:

The body is always the same envelope:

{ "event": "reply.received", "timestamp": 1786174818273, "data": { } }

Verifying the signature

Sign the raw body bytes, before any JSON parsing, a re-serialized object will not match.

import crypto from "node:crypto";
 
const expected =
  "sha256=" + crypto.createHmac("sha256", process.env.SELDA_WEBHOOK_SECRET)
                    .update(rawBody)          // the raw string, not JSON.parse(...)
                    .digest("hex");
 
// Constant-time compare, never ===
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));

Delivery, retries and disabling

• 3 attempts per event, with a 10 second timeout each
• Retry delays: 30 seconds, then 5 minutes. Byte-identical body and signature on every attempt, so a retry verifies exactly like the first try
• Any 2xx counts as delivered. Anything else is a failure
• After 10 consecutive failures the endpoint is disabled rather than retried forever. webhooks.list shows lastStatus, failureCount and disabledAt, so you can see it happened

Zapier, Make and n8n

These do not speak MCP and do not need to. Point webhooks.create at a Zapier Catch Hook (or a Make/n8n webhook node) and events arrive as plain JSON. In the other direction, Webhooks by Zapier can POST to https://api.selda.ai/mcp/mutate with an Authorization: Bearer sk_… header and a {"fn":"leads.add","args":{…}} body. No integration to install on either side.

What MCP does not do

This is the shortest section and the most important one. Everything below is a deliberate absence, not a gap waiting to be filled, and none of it is coming later.

It cannot send

There is no fn that sends a campaign. Sending is launchRun, and launchRun is not in any registry, has no tool wrapper, and never will be. A script can go all the way to drafted messages sitting in review. A person opens Selda and presses send.

This is the product, not a limitation of the API. Anyone can build a thing that mails 10,000 strangers overnight; the reason Selda’s messages get replies is that a human looked at each one before it went. An API that could bypass that would be selling something different.

Nothing here changes it: not a parameter, not a flag, not a header, not a plan, not an add-on. selda_ingest_event can create a lead and put it on a live campaign, and that lead still waits in review with no message written. If you find a way to make Selda send from a script, that is a bug and we want to hear about it.

It cannot grant itself permission

autoAdvance is a value you pass. It is recorded on the run and visible in the app, so a person can see that a script asked to go further and how far. There is no call that turns a gate off, and no call that approves a draft on a human’s behalf. (messages.approve marks a draft approved; it still does not send it.)

It cannot create a workspace

A workspace is set up by a person in the Selda app. There is no fn for it, by any key: it was removed rather than gated, because a rule enforced by a plan tier is a rule with a price on it. Once the workspace exists, everything inside it can be built and grown from a script: the Brain, the knowledge, leads, your own material, campaigns.

It cannot read another organization

Every call is scoped to the key’s organization, injected server side from the validated key. An orgId in your request body is ignored. The admin scope is cross organization, exists for internal tooling, and is never issued by self service key creation.

A free test key cannot make the engine find people

A test key is free on every plan and gives you the whole product to build against. It can read everything in the workspace and write your own data in. It cannot run the parts that spend real money to discover or enrich a real person. See Test keys and live keys.

The Brain: what Selda knows about your business

The Brain is the structured half of a workspace’s knowledge: products, partners, references and proof, company facts, notes, and the hard rules Selda must never break. (knowledge.get / knowledge.set are the other half, free prose.) Both feed every message Selda writes.

This is what makes it possible to stand a workspace up from a script. The workspace itself is created by a person in the app; everything inside it can be filled and grown from here.

All four are free on a test key.

Item types

Exactly six, and a value outside them is refused rather than stored. An item the app cannot render is an item nobody can see, edit or delete, which is worse than a rejected call.

Example

// POST /mcp/mutate
{ "fn": "brain.add", "args": {
    "projectId": "<workspace id>",
    "type": "reference",
    "title": "Summer campaign 2026",
    "body": "Ran this campaign for six weeks and booked 14 meetings from it."
}}
// -> { "value": { "ok": true, "id": "m2x8k1-3-a9f2", "count": 7 }, "request_id": "req_..." }

// POST /mcp/query   { "fn": "brain.list", "args": { "projectId": "<workspace id>" } }
{
  "value": {
    "types": ["company", "product", "partner", "reference", "avoid", "note"],
    "items": [
      { "id": "m2x8k1-3-a9f2", "type": "reference", "title": "Summer campaign 2026",
        "body": "Ran this campaign for six weeks...", "createdAt": 1785321674000 }
    ]
  },
  "request_id": "req_9f2c1a4b7e0d3a6f8c2b1e05"
}

brain.update and brain.remove answer { "ok": false, "reason": "not_found", "id": "..." } when that id is not in the workspace, rather than reporting a success that changed nothing.

What you write here may be quoted verbatim in a message to a real customer. Keep it factual. An invented reference in the Brain becomes a lie in an email.

Inbound: telling Selda something happened

Every other lead in Selda starts from Selda’s own search. events.ingest is the other direction: your website, your form, your ad landing page, your own tooling reports that something happened, and Selda works out what that means.

One call. Not “add the lead, then write the note, then attach it to a campaign” with your code holding the order straight.

• new person, so a lead is created
• somebody Selda already knows, so the event lands on their existing lead
• an address that asked Selda to stop, so nothing is created and you are told why

MCP tool: selda_ingest_event. HTTP: POST /mcp/mutate with fn: "events.ingest". Requires the Selda Inbound add on on a live key. Free on a test key, so you can build the whole integration before you buy anything.

autoAdvance: the answer is written before anyone looks

Without it, an arriving lead is stored and nothing else happens: status: new, no messages. The lead is safe and somebody still has to notice it, open it and start from a blank box.

Pass autoAdvance: true and Selda reads the workspace’s Brain, its price list, its offer rules, its tone, and the things it has forbidden itself to say, writes the reply in the language the enquiry was written in, and leaves it in the Sales Inbox. Then draft.ready fires, so you find out because you were told rather than because you checked.

It is off by default because it spends credits, and it never sends. The draft waits for the same human approval as every other draft in Selda.

If the workspace has no Brain material to answer from, nothing is drafted and draft.failed says no_brain_material. That is deliberate: a quote answered from an empty Brain is an invented price, and an invented price approved by somebody who assumed Selda knew the real one is worse than no draft at all.

Request

{
  "fn": "events.ingest",
  "args": {
    "projectId": "<workspace id>",       // required
    "type": "form_submitted",            // required. Your own wording.
    "identity": {                        // required. At least one of email / linkedinUrl / a name.
      "email": "matti@example.fi",
      "domain": "example.fi",             // context only, never used to decide identity
      "linkedinUrl": "https://www.linkedin.com/in/matti/",
      "name": "Matti Meikalainen",       // or firstName / lastName separately
      "company": "Example Oy",
      "jobTitle": "CTO",
      "phone": "+358 40 1234567"
    },
    "payload":    { "form": "analysis", "findings": ["Languages: missing"], "price": 290 },
    "source":     "example.com",
    "occurredAt": "2026-08-06T10:21:14.152Z",   // ISO 8601 or epoch ms. Defaults to now.
    "idempotencyKey": "report-example.fi-2026-08-06",
    "attachToRunId": "<campaign run id>",       // optional
    "analysis":  "Full research write-up...",   // optional, grounds the eventual message
    "tags":      ["inbound", "analysis"]
  }
}

Response

{
  "value": {
    "leadId": "k57f...",
    "created": true,
    "matchedExisting": false,
    "matchedBy": null,
    "blocked": false,
    "reason": null,
    "eventId": "j92a...",
    "replayed": false,
    "attached": { "ok": true, "runId": "m31c..." },
    "identityScanTruncated": false,
    "occurredAtFallback": false,
    "message": "Lead created and waiting for review. Nothing has been sent."
  },
  "request_id": "req_9f2c1a4b7e0d3a6f8c2b1e05"
}

Every field is always present, so you never have to decide whether a missing key means false or means the field does not exist.

Identity is a person, never a company

Matching is on the email address, and failing that the LinkedIn profile. Never the domain.

Two people at the same employer share a domain, and merging them would attach one person’s history to the other with no way to tell afterwards. So domain is stored as company context and is never allowed to decide who someone is. A near miss creates a new lead you can merge by hand, which is recoverable. A wrong merge is not.

An event carrying only a domain is refused, because it names an employer and not a person.

Retries are safe

Pass an idempotencyKey and a repeat returns the first result with replayed: true, creating nothing. This is what lets you call Selda from a webhook handler that has no way of knowing whether its first attempt landed.

Joining a campaign

attachToRunId puts the lead on an existing campaign’s review list. The campaign already has a tone, a signature, a follow up rhythm and safety rules that somebody approved; an inbound lead joining that beats it inventing a process of its own.

It joins at review, with no message written. A launch selects drafts that are written, approved or queued. A row created this way is none of those, so no launch can pick it up and a human sees it first, exactly like a discovered lead.

Errors specific to this call

Flows: what happens when something arrives

events.ingest records what happened and can draft a reply. A flow is the layer above it: the workspace has said, once, what should happen to an arrival like this one, and the same definition is readable and writable from here and from the app.

A flow is a trigger plus ordered steps.

{
  "name": "Website enquiries",
  "trigger": { "kind": "inbound_event", "eventTypes": ["widget_enquiry"], "sources": ["example.com"] },
  "steps": [
    { "id": "s1", "kind": "understand", "skillId": "<from flows.saveSkill>",
      "categories": [
        { "key": "video", "label": "Video production", "hint": "shoots, edits, event coverage" },
        { "key": "seo",   "label": "Site and SEO",     "hint": "visibility, rebuilds, bookings" }
      ] },
    { "id": "s2", "kind": "route",
      "routes": [
        { "categoryKey": "video", "runId": "<campaign run id>" },
        { "categoryKey": "seo",   "inboxOnly": true }
      ] },
    { "id": "s3", "kind": "draft_reply" },
    { "id": "s4", "kind": "notify", "emails": ["you@company.com"], "webhook": true }
  ]
}

An empty eventTypes or sources means any. trigger.kind may also be manual, for a flow you only run by hand while you are writing it.

The steps, and the line they cannot cross

There is no sending step and there will not be one. launchRun is refused by path for every key, and a flow’s furthest act is a draft plus a notification. That is the same gate a person meets in the app, not a weaker one for automation.

When a flow and autoAdvance both write

If a flow matching the event has a draft_reply step, it owns the drafting and events.ingest’s own autoAdvance stands down. The response says so (autoDraft.reason: "flow_writes_it") and lists the flows the event set off, so nothing has to be inferred from an inbox that looks emptier than expected.

Reading what it did

flows.runs returns every step of every run with a status of ok, skipped or failed and a summary in plain words. A skip is a row with its reason, never an absence. That is the thing to read when a flow behaves unexpectedly, rather than re-reading its definition.

Test keys and live keys

Two kinds of key, and the difference is not “test data versus real data”. It is what Selda is allowed to spend on your behalf.

• sk_test_… test key. Free on every plan, including Free. Read everything in the workspace, write your own data in, build and test a whole integration.
• sk_live_… live key. Requires a paid plan (Pro and up). Adds the parts that cost money: finding people, enriching them, running discovery, and reaching a real recipient.

What a test key can do

Everything you need to build against Selda without paying:

• every read: projects.*, leads.list / leads.get, campaigns.*, runs.status, messages.*, knowledge.get, brain.list, credits.info, connectors.list, webhooks.list
• every write of your own data: leads.add / addBatch / update / addTag / merge / delete, knowledge.set / append, brain.add / update / remove, projects.updateContext, campaigns.* (the legacy table), messages.approve, webhooks.*, connectors.create / delete
• POST /mcp/material/upload and material.import without autoAdvance
• events.ingest, so you can build and test an inbound integration end to end
• messages.generate, replies.draft, replies.classify: drafting against the companies you already have is the point of test mode

What needs a live key on a paid plan

There is no send function, on any key. This table used to list messages.send as something a live key unlocks. No such function exists in the registry and none is planned: sending happens only in the Selda app, after a human approves each message. A live key buys the calls above, which spend money or reach a provider, never the one that reaches a recipient. GET /mcp/capabilities has always said so in its own note; this page did not.

A test key calling one of these gets a 403 whose message is a sentence explaining what the call does, why it needs a live key, and what your key can still do. The machine readable form is in code:

{
  "error": {
    "type": "authorization_error",
    "code": "live_key_required:paid_contact_data",
    "message": "This looks up real people's contact details through paid data providers, so it needs a live key on a paid plan. Your test key can still add companies you already have, import your own material, and draft against them.",
    "request_id": "req_9f2c1a4b7e0d3a6f8c2b1e05"
  },
  "request_id": "req_9f2c1a4b7e0d3a6f8c2b1e05"
}

The reasons you can get back: paid_contact_data, paid_engine_run, external_sync, workspace_creation, sending, admin_only.

Each capability in GET /mcp/capabilities carries sandboxAllowed and liveOnlyReason, so you can read the whole line off the manifest instead of discovering it one 403 at a time.

Errors

Every failure has the same shape, on every endpoint:

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_fn",
    "message": "Unknown query: leads.lst. Available: projects.list, projects.get, …",
    "request_id": "req_9f2c1a4b7e0d3a6f8c2b1e05"
  },
  "request_id": "req_9f2c1a4b7e0d3a6f8c2b1e05"
}

request_id also comes back in the X-Request-Id response header, so you can log it without parsing the body. It contains nothing secret. Quote it in a support message.

An invalid_api_key and a projectId outside your organization deliberately look the same as “no such thing”: a key must not be able to probe what exists in someone else’s workspace.

Limits

Nothing here expires a key on its own. Keys live until you revoke them.

What things cost

There is no per tool price list, and publishing one would be a guess. Selda charges from observed spend: every LLM call and paid vendor call reports its real cost, the run accumulates it, and credits are that spend times a fixed margin. A discovery run over ten hard to research companies genuinely costs more than one over ten easy ones, and a price table would have to lie about that in one direction or the other.

What is true and worth planning around:

• Reads are free. No query on /mcp/query costs a credit. Neither does receiving a reply, registering a webhook, or anything in the Brain.
• Writing your own data in is free. leads.add, material.upload, material.import without autoAdvance, knowledge.*, brain.*. You are not charged for handing Selda what you already had.
• Work Selda does costs. Discovery, research, enrichment, message writing, sending. That is engine.start, company.lookup, leads.enrich*, messages.generate, material.import with autoAdvance, and connectors.sync.
• Selda’s own failures are never charged. A run that errors and retries is our cost.
• Test-mode work is charged at the same margin as paid work. The free tier’s gift is the SIZE of its grant, 30 credits, about one full run, not a discounted rate, so what a credit buys is the same number wherever you are.

Call credits.info before and after a run to see the actual number for your workload. That is the only honest way to size it, and it is one call.

Tools

Note what is not here: earlier versions of this server had selda_create_campaign and selda_add_leads_by_tag, which wrote to a legacy campaigns table the campaign-flow UI does not read, so a campaign created that way was invisible in the app. They were removed. To create a real, reviewable campaign, use selda_upload_material + selda_import_material below: it creates one via the same path the browser’s folder-drop uses.

The table below is generated from the servers themselves. It carried a hand-written list of 22 tools until 3.9.2026, while the hosted server had 62 and the sentence above it said both servers exposed the same set. Both numbers and the claim were wrong, and nothing was checking. Now a tool added to a server is a row on this page or a failing test.

The hosted server serves 68 tools. The local stdio server serves 36, a subset: 36 of the hosted tools are on both, and 30 are hosted only. They are not interchangeable, so pick the hosted one unless you specifically need a local process.

The two tools ChatGPT looks for

OpenAI’s connector contract does not read tool descriptions to decide what a server can do. It requires two tools by NAME, with fixed argument and result shapes, and a server without them connects and then has nothing ChatGPT will call. Selda serves both. They are a read-only view over the tools below, not a second data path, and every id search returns is one that fetch accepts.

// search({ query: "nordic books" })
{ "results": [ { "id": "lead:k57...", "title": "Mika Virtanen · Nordic Books Oy", "url": "https://app.selda.ai/workspace-..." } ] }
 
// fetch({ id: "lead:k57..." })
{ "id": "lead:k57...", "title": "Mika Virtanen · Nordic Books Oy", "text": "Name: ...\nResearch: ...", "url": "...", "metadata": { "kind": "lead", "draftWaitingForApproval": true } }

Ids are lead:…, project:… and brain:…. An id of any other shape is a tool error, not an empty result, so a client cannot quietly show nothing.

Everything else

Arguments marked ? are optional. A tool marked * is on the hosted server only.

* marks a tool the hosted server has and the local stdio server does not.

Usage guidance (from the MCP server instructions)

• The app is at https://app.selda.ai, never use selda.city or other domains.
• Always call selda_list_projects first to obtain a projectId before any other operation.
• When a user shares a URL or webpage with specific companies/people, add them directly (e.g. selda_add_lead), do not pass URLs to selda_run_pipeline.
• Use selda_run_pipeline only for open-ended searches like “find SaaS founders in Finland”.
• selda_run_pipeline runs the engine and costs credits. It stops at the company list and waits for a person in the app; poll selda_get_run_status and read awaitingHuman before saying anything about whether it finished.

Connecting a client

OAuth (recommended for Claude.ai, ChatGPT, Cursor): add https://mcp.selda.ai/api/mcp as a connector. The server advertises WWW-Authenticate: Bearer resource_metadata=… on an unauthenticated request, pointing at GET /.well-known/oauth-protected-resource, which in turn points at the authorization server’s GET /.well-known/oauth-authorization-server (https://api.selda.ai). A client that supports this discovers the whole flow automatically: it self-registers via POST /oauth/register (RFC 7591, no human step), sends the user’s browser to authorization_endpoint (https://app.selda.ai/oauth/authorize) where they log in and approve a workspace, then exchanges the resulting code for an access token via POST /oauth/token (Authorization Code + PKCE, code_challenge_method=S256). The access token is a regular sk_live_… key under the hood, same org-scoping, same revoke button in Settings → Apps → Selda MCP. OAuth is just a way to mint it without copying anything by hand.

Static key (Claude Code, scripts, CI):

1. In the Selda app go to Settings → Apps → Selda MCP and create a key. Copy the sk_live_… value (shown once).

2. claude mcp add --transport http selda https://mcp.selda.ai/api/mcp \
     --header "Authorization: Bearer sk_live_xxx"
   Or the equivalent JSON block for any other client that reads MCP config (Claude Desktop, Cursor), same URL, same header, no local install.
3. Every call is automatically scoped to the org that owns the key. Pipeline runs consume credits, so check selda_credits if runs start failing.

Local stdio (mcp-server/index.ts) still exists for local development, spawned by a client via npx tsx with SELDA_API_KEY in its environment, but the hosted server above is the current recommended path for every client that supports remote MCP.

Changelog

Tool arguments and response shapes change here first. A dated entry means the behaviour is live.

2026-08-06

Added: selda_ingest_event / events.ingest. One call for an inbound lead: creates the person if new, recognises them if known, records the event on their timeline, optionally joins a campaign. Identity matches on email or LinkedIn profile, never on the company domain. Supports idempotencyKey for safe retries. Requires the Selda Inbound add on on a live key; free on a test key. It cannot send.

Added: the Brain over MCP. brain.list, brain.add, brain.update, brain.remove and their selda_*_brain_item tools. The structured knowledge a workspace is built from was previously readable only in the app.

Changed: selda_update_lead appends notes instead of replacing them. Its description always said “notes to add” and it overwrote. Pass appendNote: false for the old behaviour. The raw leads.update fn still replaces by default, so a direct HTTP integration is unaffected; opt in with appendNote: true.

Changed: leads.add refuses a suppressed address. It returns blocked: true with a reason and creates nothing, instead of creating a lead that may never be contacted. Its response now always carries leadId, duplicate, blocked and reason, so the shape no longer varies by path.

Changed: test keys are no longer allowed to spend. A test key can read the whole workspace and write your own data in, but company.lookup, leads.enrich*, engine.start, connectors.sync and material.import with autoAdvance now need a live key on a paid plan, and projects.create was removed from the API entirely. The refusal is a 403 with code: "live_key_required:<reason>" and a sentence explaining it. If your integration used a test key for contact lookup, this is a breaking change and it is deliberate.

Added to GET /mcp/capabilities: sandboxAllowed, liveOnlyReason and requiresEntitlement per capability, so the limits are readable rather than discoverable one error at a time.

Documented: the error envelope and every code, per key rate and size limits, what actually consumes credits, a single canonical transport answer, and What MCP does not do.

Source files