Siftable MCP Server

A Model Context Protocol server that exposes Siftable tools to IDE clients like Cursor, Claude Desktop, and VS Code.

ExecuFunction 0.4.0.0 hosted compatibility

The npm package is 1.3.0; the hosted and source projection profile is 1.34.0. Projection 1.34.0 standardizes bounded collection receipts, publishes dataset aggregate semantics, and distinguishes OAuth connections that must reconnect from sessions that can widen authorization in place. Projection 1.33.0 recognizes natural-language source-search intent and returns the retired capability card with local recovery rather than routing the request to curated code memories. Projection 1.32.0 added an explicit no_matches discovery outcome, rejects generic-operation and weak-prefix-only capability matches, preserves canonical compound-intent matches, and captures HTTP status classes in failure receipts. Projection 1.31.0 added governed lead-discovery scope requirements. Projection 1.29.0 added managed work-lease sessions for hosted clients while keeping claim tokens server-side. Projection 1.28.0 added four governed lead-discovery tools and five app-equivalent person/organization enrichment tools.

Lead discovery is disabled by default. When enabled, it requires separately granted lead_discovery:read or lead_discovery:write scopes; mcp:* does not imply either scope. Hosted baseline catalogs therefore omit company search until request_capability approval and a catalog refresh expose the hosted-capable tool. A company search is bounded to one paid Crustdata request, shows a maximum charge before dispatch, settles the actual provider credits, and saves results only as review candidates. Canonical CRM records are created through lead_discovery_import_plan_create followed by the existing crm_import_plan_approve and crm_import_plan_apply review gates.

Person enrichment returns stored profile and fact proposals. Apply accepts only proposal field names and fact IDs rehydrated from the completed run; it does not accept free-form replacements and is not retry-safe. Organization enrichment remains the app's paid preview-only flow and cannot apply canonical CRM changes.

1.3.0 compatibility note

Version 1.3.0 publishes sift.dataset.query.v2, versioned aggregate receipts, uniform work-item collection metadata, and the reconnect_required capability state. Consumers that validate the previous dataset-query receipt should select behavior by schemaId.

1.2.42 compatibility note

Version 1.2.42 closes the publication-readiness audit. Natural-language source search discovery returns the canonical retired/local-only recovery card, while curated code-memory discovery remains distinct. The hosted setup guide now gives exact ChatGPT and Codex configuration steps.

1.2.41 compatibility note

Version 1.2.41 closes two hosted audit failures. Dataset routes reject malformed dataset UUIDs at the HTTP boundary, and MCP receipts preserve the resulting 400 as bad_request. find_capability now requires a direct domain signal plus an aligned operation; unrelated intent returns queryOutcome: no_matches with empty capability lanes and rephrase guidance. Exact tool names, removed-tool cards, and virtual orientation tools bypass semantic rejection.

1.2.40 compatibility note

Version 1.2.40 addresses the third round of live agent QA (the 2026-08-22 hosted audit).

• claimability is honest about lifecycle and lease state, not only dependencies: state is one of ready, waiting, dependency_failed, leased, lease_expired, blocked, in_review, human_review_gate, or terminal, with claimable, reason, and nextAction alongside blockedBy. Claimed, running, cancelled, and done work no longer advertise ready; claimable is the authoritative boolean (a lease_expired item and a legacy-converted blocked placeholder whose predecessors are satisfied are claimable: true because an explicit claim recovers them). Claiming a non-claimable item by ID returns a 409 that names the state (lease_active, work_item_terminal, …) instead of not_found. The CLI and TUI gate on claimable when the server provides it.
• agent_work_list and work_item_list hide done/failed/cancelled items by default (includeTerminal: true or an explicit status shows them), print their ordering rule, and document that higher queueRank sorts earlier, 0 is the default, and negative ranks are deferred (they sort after 0).
• work_item_heartbeat says that a heartbeat on claimed work starts it (claimed → running, same as work_item_start); resultSummary passed to start, heartbeat, or release is now persisted instead of silently dropped.
• task_get lists the executable work joined to the task (first ten, with a marker when more exist; "none yet" with the work_item_create hint when empty) when the connection can read work items; a missing scope keeps the capability hint and an upstream failure is reported as such (single attempt, no retry).
• entity_graph reports each record's own status where it has one (a completed task is completed, not active; notes/datasets active/archived; connected projects now carry their name and status instead of [untitled entity]/active) — migration V400 fixes the SQL function that labelled every non-note node active and never joined projects. Other node types keep their type-specific label in that slot (organization industry, person relationship, news published date).
• note_search ranks full-text matches (websearch syntax) ahead of semantic neighbours, then literal-substring fallbacks, instead of sorting raw scores on different scales; scores are comparable within a source, not across.
• object_find distinguishes an unknown object type key from a known type with zero records.
• Code-memory listings label a confirmed fact without chunk evidence as not_recorded (confirmed; no source-chunk evidence recorded) so the evidence gap is visible without downgrading human-admitted facts.

Projection 1.25.0 keeps hosted OAuth catalogs limited to tools callable with the current token. find_capability still discovers tools that need scope elevation, and those tools appear after authorization and a catalog refresh. The server initialization guidance is also shorter so clients do not repeat a large instruction block across tool descriptions.

1.2.39 compatibility note

Version 1.2.39 addresses the second round of live agent QA.

• work_item_requeue also returns a claimed/running item whose lease has expired to the queue, without the original claim token; active leases are still never requeued. work_item_list labels expired leases inline ([claimed · lease expired <time>]), and work_item_get prefixes its JSON with a Lease: expired <time> — … header saying the item is claimable as-is or requeueable, instead of showing plain claimed.
• work_item_revision_history / work_item_verification_history say so in a sentence when there is nothing recorded instead of printing [].
• object_find names the object type it searched and points at schema_introspect / people_search / organization_search when nothing matches, instead of a bare "No objects found."
• schema_introspect summarises datasets (title, ID, rows, field count) by default; includeDatasetFields: true restores the per-field dump.
• dataset_quality_check counts blank strings as missing values and returns a versioned structured result. Frequently repeated values are observations; they are only quality violations when a field is declared unique.

Projection 1.22.0 records the schema_introspect input schema and the tool description changes.

1.2.38 compatibility note

Version 1.2.38 makes the agent path to work authority direct instead of a scavenger hunt (decision 2026-08-20, after live use from Grok and Claude).

• Hosted OAuth first connect (no scope parameter, or scopes_supported copied by the client) is issued mcp:* work:read work:write behind the consent screen. Vault and AI scopes remain step-up/CLI-only.
• Tools the connection could acquire through step-up are presented on tools/list; calling one before approval returns an in-band tool error carrying the same elevation link (or CLI/PAT guidance). The HTTP 403 insufficient_scope challenge is now issued only for request_capability in challenge mode.
• Elevation links live for one hour (was ten minutes); after an approval the server publishes tools/list_changed so subscribed clients refresh, and the guidance tells the agent to refresh the tool list or restart the connector if the tools are still hidden.
• find_capability, request_capability, and context_current render a compact text summary (name, availability, next step) instead of the full JSON; the complete projections remain in structuredContent.
• task_get and the task tool descriptions no longer claim work:read is missing; they point at work_item_list with taskId and defer to request_capability only when the tool is not callable.
• "Stable handles" in generic list text now name the field each ID came from and group repeats, so a projectId shared by twenty rows reads as one project reference rather than twenty new records.

Projection 1.21.0 records the presented-tool and description changes. Reconnect hosted MCP clients after upgrade to refresh the projection 1.21.0 schemas.

1.2.37 compatibility note

Version 1.2.37 makes scope step-up reachable from the agent's seat on hosted OAuth connections instead of depending on the client re-running OAuth.

• request_capability (inspect) now returns elevation — a short-lived (ten-minute), owner-bound approval link for the connected OAuth token, replayable by the owner within its window — on Streamable HTTP whenever the missing scopes are elevatable (work:read, work:write) and the server supplied capabilityAcquisition.createElevationGrant. The user opens the link, re-authenticates, approves on the first-party consent screen, and the existing token is widened in place; the agent retries the tool without reconnecting. recommendedNextAction.type is open_elevation_url in that case and reconnectRequired is false. The reconnect guidance remains the fallback for connections that cannot be elevated.
• find_capability, context_current, and direct gated-tool rejections point at that path instead of at a client reconnect.
• Hosted OAuth now accepts an explicit work:write request (consent-gated); in 1.2.37 the authorize default when a client omits scope was mcp:* work:read and scopes_supported advertised only that pair (both widened to the full work family in 1.2.38).

Projection 1.20.0 records the request_capability output schema and description change. Reconnect hosted MCP clients after upgrade to refresh the projection 1.20.0 schemas.

1.2.36 compatibility note

Version 1.2.36 prepares the hosted endpoint for ChatGPT plugin-directory publication without changing the stdio tool surface.

• upload_document no longer advertises filePath on the hosted profile: the hosted schema requires inline content and filename, and a filePath argument is rejected with a normalized bad_request failure at the MCP boundary, at executeTool, and inside SiftClient unless the client was constructed with allowLocalFiles. Only the local stdio entrypoint sets that flag; hosted and remote clients can never reach the server's filesystem.
• Hosted tools now carry OpenAI-only hints under _meta, which other MCP clients ignore by specification: securitySchemes listing only the scopes the connected OAuth client can actually request (baseline mcp:*), and tool-invocation status strings derived from each tool's title.
• Every catalog tool now publishes an outputSchema: the 27 read-only query tools that lacked one declare the sift.action_receipt envelope with a text/plain result, matching what tools/call already returns.
• Projections and catalog digests are computed from the transport-shaped schema, so hosted find_capability and schemaDigest describe the tool surface the client is actually presented.

Projection 1.19.0 records the hosted upload_document schema and the envelope output schemas. Reconnect hosted MCP clients after upgrade to refresh the projection 1.19.0 schemas.

1.2.35 compatibility note

Version 1.2.35 closes the remaining contract divergences found in the 1.2.32 review.

• schema_introspect now exposes datasets only when both the deployment-wide dataset switch and the caller's feature grant allow the dataset routes. Its dataset and object-type queries now run with the caller's RLS identity.
• code_memory_delete returned 500 for every memory that had ever existed. V351 gave the lifecycle event log an ON DELETE CASCADE foreign key and an append-only trigger that raised unconditionally, so the cascade aborted every delete. V389 lets the referential cascade through while still refusing a direct edit of the log, repairs two lineage foreign keys that would have nulled a NOT NULL owner column, and returns an orphaned predecessor to needs_review with an audit event when its successor is deleted.
• Human admission actions are no longer callable over MCP. code_memory_confirm, code_memory_reject, code_memory_edit, and code_memory_supersede are hidden and refused on both hosted and local agent transports. Agents may store candidates or mark facts needs_review; a human curates them in the Siftable interface.
• project_get_context reported each task's workflow phase in its status field and left phase null. Both are now the real column values, on open, blocked, and overdue tasks alike.

Projection 1.18.0 records that human-curation boundary and removes four tools from the presented agent surface.

This release requires migration V389__code_memory_delete_cascade.sql. code_memory_delete continues to fail until it is applied.

1.2.34 compatibility note

Version 1.2.34 closes a set of defects where a call succeeded but the answer was wrong or incomplete.

• Writing a person with a company returned 500 unconditionally. The organization upsert named a unique index that became partial in V357 without supplying its predicate, so Postgres could not infer the conflict target.
• Authored content is no longer stripped in transit. The request pipeline ran striptags() over every string, which deleted < from filter operators, turned List<String> into List, and removed markup from note titles — silently, and for every MCP call, because the content allowlist only matched top-level body keys. HTML is now escaped where it is rendered instead.
• A range comparison (> >= < <=) against a text-typed column with a numeric value is rejected with the retype path, instead of quietly comparing as text where '99' sorts above '199'. Sorting such a column returns a warning rather than an unmarked, plausible, wrong order.
• dataset_query now carries warnings in its structured result.
• task_get now carries the full task brief structurally — rationale, deliverable, verification, approachConstraints, acceptanceCriteria, and scope. Structured-first clients previously received a task with no definition of done.

Reconnect MCP clients after upgrade to refresh the projection 1.18.0 schemas.

1.2.33 compatibility note

Version 1.2.33 repairs hosted OAuth token exchange. The authorization server looked up a hashed authorization code with a consumed_at IS NULL filter against a table that consumes codes by deletion and has no such column, so every fresh Connect from Cursor, Codex, or any other remote client failed with Internal Server Error after Google consent. Existing authenticated sessions were unaffected. Tool contracts and projection 1.16.0 schemas are unchanged; no reconnect is required beyond retrying a login that previously failed.

1.2.32 compatibility note

Version 1.2.32 adds an explicit, metadata-only repository_project_link mutation so an agent can persist the project selected from context_current.projectCandidates. It also keeps unsupported-client matches in a secondary discovery lane and suppresses zero-score full-text note hits.

Reconnect MCP clients after upgrade to refresh the projection 1.16.0 schemas.

Hosted remote clients

The recommended hosted endpoint is:

https://siftable.io/api/v1/mcp

Claude remote connectors, Cursor, Codex, Devin, Kimi Code, and Antigravity can connect over Streamable HTTP. Prefer URL-only OAuth configuration: an authorize request that omits scope is issued mcp:* work:read work:write by default behind the first-party consent form, and anything missing later can be approved in place through the one-hour link request_capability returns (Streamable HTTP only; legacy /sse sessions reconnect instead). A configured Authorization header selects static PAT mode; that token's scopes cannot be expanded by an OAuth challenge or an elevation link.

Client configuration keys and callback behavior differ (url in Cursor, Codex, and Kimi; serverUrl in Antigravity; UI-managed connections in Claude and Devin). See docs/runbooks/hosted-mcp-client-compatibility.md for the provider-grounded matrix and verification flow.

The npm package remains the local stdio path for clients that need an authorized checkout or cannot use the hosted endpoint.

MCP Apps views

Some tools can render in a sandboxed View in hosts that implement the MCP Apps extension (Claude, ChatGPT, VS Code, Goose). Those tools carry _meta.ui.resourceUri pointing at a ui://siftable/<view>.html resource, listed by resources/list and served by resources/read with the MIME type text/html;profile=mcp-app. The metadata is presentation only: it never changes a tool's projection, scopes, presented catalog, or catalog digest, and content stays a complete text answer for every other client.

UI metadata is attached only when the View bundle exists in dist/ui/. A build without bundles presents no UI metadata at all. The reviewed tool to View allowlist lives in src/ui/viewRegistry.ts; the design is in docs/design/mcp-ui-surfaces-plan.md.

The bundles are built by the @siftable/mcp-apps workspace (packages/exf-mcp-apps, one self-contained HTML file per View) and copied into dist/ui/ by scripts/copy-ui-bundles.mjs at the end of npm run build. Through Nx the apps workspace builds first (nx run @siftable/mcp-server:build). A plain npm run build without an apps build, which is what the hosted Docker image does today, copies nothing and stays inert. verify:package, prepublishOnly, and pack:mcpb build the apps first and fail if a bundle is missing, so a published tarball or .mcpb always carries every View bundle (dist/ui/graph.html, data.html, review.html).

Views available today:

Human gate on consequential tools

Seven tools ask the human to confirm before they run: the four bulk deletes on their apply call (confirm: true with a previewId; previews and dry runs never prompt), dataset_schema_modify when it deletes a field, crm_import_plan_approve, and lead_discovery_company_run, whose prompt states the approved ceiling in USD. The question travels as an MCP 2026-07-28 multi-round-trip InputRequiredResult carrying one form elicitation with a single confirm boolean; the client shows it, then retries the same call with inputResponses. On 2025-era sessions that have a backchannel (stdio or sessionful HTTP) the SDK's legacy shim sends the same prompt as an elicitation/create request. On the stateless 2025 HTTP fallback no client capabilities are known per request, so the gate is not asked.

A client that declares no elicitation capability runs the tool as before. Every gated receipt, whether it succeeded, failed, or was rejected, records the gate under humanGate: elicitation with accepted, or unsupported_fallback with not_asked, on receipts where the tool ran; and elicitation with the exact refusal, declined, cancelled, or not_confirmed, on the rejected receipt (error.code: "declined_by_user") where nothing ran. The gate is a human-in-the-loop guarantee for honest hosts; OAuth scopes remain the authorization boundary. The seeded tool list is in src/registry/mcpToolContractSeed.ts and the wording in src/humanGate.ts.

1.2.31 compatibility note

This release keeps task collection totals stable across cursor pages, resolves repository context through durable identities under transaction-scoped RLS, and returns explicit project candidates instead of auto-linking repositories by name. Project resources now paginate with opaque cursors and surface backend failures, while graph and people results provide usable canonical labels. Reconnect MCP clients after upgrade to refresh the projection 1.15.0 schemas.

1.2.30 compatibility note

This release requires caller-stable idempotency keys for agent creation, work claims and lifecycle transitions, code-memory writes, document uploads, Vault entry creation, and governed approval, execution-grant, and materialization requests. Same-key retries replay the original authoritative response; changed payloads conflict. Vault receipts retain metadata or runner-encrypted ciphertext, never plaintext. ai_generate remains explicitly non-retry-safe because streamed provider output is not persisted for replay. Reconnect MCP clients after upgrade to refresh the projection 1.14.0 schemas.

1.2.29 compatibility note

This release makes hosted capability inspection terminal and reconnect-safe, adds task-state and governed-approval invariants, and puts stable IDs and typed details into project, task, dataset, schema, people, organization, and calendar results. Retired source-index/search names route to local checkout search while curated code memories remain available. The dataset_create, dataset_mutate, dataset_schema_modify, and dataset_materialize_result tools require a caller-stable idempotencyKey. Reusing the same key with the same payload replays the original result; reusing it with a changed payload is rejected. Existing MCP sessions must reconnect to refresh their cached tool schemas before invoking these mutations. Direct REST callers remain backward compatible when the Idempotency-Key header is omitted.

Privacy Policy

The server sends tool calls to the Siftable API at the configured SIFT_API_URL (by default https://siftable.io) and to nothing else. It stores no data locally beyond the environment it is started with, and the personal access token is only ever sent to that API. Siftable's privacy policy, covering collection, use, storage, sharing, retention, and contact details, is at https://siftable.io/privacy.html.

Distribution artifacts

@siftable/mcp-server is published from the monorepo; the public source mirror at https://github.com/execufunction-mcp/mcp-server is refreshed with scripts/mirror-mcp-server.sh and cannot build on its own.

manifest.json is the desktop-extension manifest; its version must match package.json and the bundle build asserts it. The bundle carries its own production node_modules, so it runs without the monorepo.

Quick Start

1. Create a Personal Access Token

1. Go to Siftable → Settings → Developer → Access Tokens
2. Click "Create Token"
3. Name it (e.g., "Cursor MCP")
4. Select mcp:* for baseline MCP access, then add the specific scope families your workflows need (for example projects:read, tasks:write, or work:read). mcp:* is not universal authorization.
5. Save the token immediately - it's only shown once!

2. Configure Your MCP Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "siftable": {
      "command": "npx",
      "args": ["@siftable/mcp-server"],
      "env": {
        "SIFT_API_URL": "https://siftable.io",
        "SIFT_PAT": "sift_pat_your_token_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "siftable": {
    "command": "npx",
    "args": ["@siftable/mcp-server"],
    "env": {
      "SIFT_API_URL": "https://siftable.io",
      "SIFT_PAT": "sift_pat_your_token_here"
    }
  }
}

VS Code

Configure in your MCP extension settings.

3. Restart Your IDE

After configuration, restart your IDE to load the MCP server.

Available Tools

Orientation and capability acquisition

Start every new client session with context_current. It reports the effective workspace, project, repository, transport, presented/effective scopes, missing requestable scopes, and recommended next calls. Hosted MCP returns a null checkout plus a reason unless the client explicitly provides a root hint.

Use find_capability as the discovery entry point when a tool is absent or an operation is unauthorized. Call request_capability in inspect mode to get a structured recovery plan without triggering an authorization challenge; use challenge mode only when the client can render the standards-compliant OAuth action from the HTTP 403 response.

When no candidate meets the discovery confidence contract, find_capability returns queryOutcome: no_matches, zero counts, and empty lanes. Rephrase with both a Siftable domain and operation, or inspect tools/list; do not treat a zero-result response as authorization evidence.

task_* manages human planning. work_* manages executable agent work. Prefer the stable IDs returned by collection and mutation results in follow-on calls.

Projects

Tasks

Agents

Work Items

Knowledge / Notes

People

Organizations

Lead Discovery

See Headless CRM import plans for the approval and apply lifecycle shared by CLI and MCP.

Calendar

Local Source Context

Source inspection and search stay local to an authorized checkout through Git, rg, the editor, or agent-native tools. Siftable stores curated code memories; it does not index or semantically search repository source.

Code Memories

Vault / Secrets

vault_read is retired. MCP never returns plaintext secret bytes; use a governed capability or an explicitly approved materialization instead.

Entity Graph

Document Upload

Datasets (feature flag: DATASETS_ENABLED=true)

Ontology (feature flag: DATASET_ONTOLOGY_ENABLED=true)

Usage Examples

1. Get project context and create a task

User prompt: "Get context for my auth project and create a task to fix the token refresh bug"

Tools invoked:

1. project_list — Lists projects to find the auth project
2. project_get_context — Retrieves tasks, notes, and signals for the project
3. task_create — Creates a human planning task with title, description, and project linkage

Result: The AI reads existing project context (open tasks, recent notes) to avoid duplicates, then creates a well-scoped task linked to the correct project.

To run an agent, create a linked executable work item with work_item_create and set taskId to the parent human task. Task tools should track planning state; work item tools should track execution, leases, artifacts, verification, and review state.

Dependencies are authoritative UUID references. Pass dependsOn as an array of { workItemId, requiredGate? }, where requiredGate is done or commands_passed. An omitted gate resolves through the project's work-dependency policy. List and get results expose the resolved dependencies projection and derived claimability (ready, waiting, or dependency_failed). Replace the complete edge set with work_item_dependencies_replace; use an empty array to remove every dependency. Historical verified gates are normalized to commands_passed during the verifier-retirement migration.

Lease-owned lifecycle calls (start, heartbeat, block, review, and fail) require both the claimOwner and claimToken returned by work_item_claim; release requires the active token. complete accepts credentials for lease-owned completion but leaves them optional so a human can resolve needs_review without a lease. cancel is likewise tokenless. Claim tokens remain omitted from get/list output and should not be logged or persisted by clients.

2. Knowledge search and note creation

User prompt: "Search for our deployment process and create a note summarizing the steps"

Tools invoked:

1. note_search — Searches the knowledge base for "deployment process"
2. code_memory_search — Searches stored code facts for deployment-related memories
3. note_create — Creates a new note with a markdown summary of the deployment steps

Result: The AI synthesizes information from existing notes and code memories into a single reference note, linked to the relevant project.

Resources

The server also exposes project context bundles as MCP resources:

• exf://projects/{id}/context - Full context bundle for a project

Environment Variables

Legacy EXF_API_URL and EXF_PAT remain supported for existing MCP configs.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Test with MCP Inspector
npm run inspect

# Build for production
npm run build

Security

• PATs are stored as SHA-256 hashes - plaintext is never stored
• Tokens can be revoked at any time from Siftable Settings
• Use minimal scopes for your use case
• Never commit tokens to version control

Scopes

Troubleshooting

"SIFT_API_URL environment variable is required"

Make sure you've configured the env section in your MCP client config.

"Invalid token"

1. Check that your token starts with sift_pat_ or legacy exf_pat_
2. Verify the token hasn't been revoked
3. Check the token hasn't expired

Tools not appearing

1. Restart your IDE after configuration changes
2. Check IDE logs for MCP errors
3. Try running npm run inspect to test the server directly

License

MIT