Siftable
Siftable MCP server for governed work, knowledge, calendar, people, datasets, and Vault.
Open source Open in the app JSON README (API)
About
Siftable MCP server for governed work, knowledge, calendar, people, datasets, and Vault.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- tom-r-main
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.4.0
- Last push
- 2026-09-07T20:20:32Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:17
- Updated
- 2026-09-07 21:05:06
- Origin id
io.github.Tom-R-Main/mcp-server
README
# Siftable MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io/) 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:
```text
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`](../../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`](../../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:
| View | Resource | Tools |
| --- | --- | --- |
| Graph | `ui://siftable/graph.html` | `entity_graph`, `object_links` |
| Data | `ui://siftable/data.html` | `dataset_query`, `dataset_aggregate`, `dataset_summarize`, `dataset_quality_check`, `dataset_facets`, `dataset_compare`, `dataset_rank`, `dataset_plot_result`, `dataset_timeseries`, `dataset_bucket`, `people_search`, `organization_search`, `task_list` |
| Review | `ui://siftable/review.html` | `lead_discovery_candidate_list`, `lead_discovery_run_get`, `crm_import_plan_get`, `crm_import_plan_create` |
## 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.
| Artifact | Command | Where it goes |
| --- | --- | --- |
| npm package | `npm publish --workspace @siftable/mcp-server` | `npx @siftable/mcp-server` for stdio clients |
| Claude Desktop extension | `npm run pack:mcpb --workspace @siftable/mcp-server` | `build/siftable.mcpb`; attach to the GitHub release and submit through the desktop-extension form |
| MCP Registry entry | `npm run publish:registry --workspace @siftable/mcp-server` after `mcp-publisher login github` | `io.github.Tom-R-Main/mcp-server`, which points at the npm package |
`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`:
```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:
```json
{
"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.
| Tool | Description | Mutates |
|------|-------------|---------|
| `context_current` | Resolve principal, owner, project, repository, checkout, and effective capability context | No |
| `find_capability` | Discover callable, missing, requestable, and unsupported capabilities | No |
| `request_capability` | Inspect recovery or request an OAuth authorization challenge | No |
### Projects
| Tool | Description | Mutates |
|------|-------------|---------|
| `project_list` | List projects with status filtering, bounded cursor pagination, stable IDs, and compact summaries | No |
| `project_create` | Create a new project | Yes |
| `project_update` | Update project name, summary, status, emoji | Yes |
| `project_archive` | Archive a project (destructive) | Yes |
| `project_get_context` | Get full project context (tasks, notes, signals) | No |
### Tasks
| Tool | Description | Mutates |
|------|-------------|---------|
| `task_list` | List human planning tasks with project/status/phase/effort/title filters | No |
| `task_get` | Get a single human planning task with full details | No |
| `task_create` | Create a human planning task with priority, phase, effort, acceptance criteria | Yes |
| `task_update` | Update human planning task fields (title, status, priority, phase, effort, scope) | Yes |
| `task_delete` | Delete a task (destructive) | Yes |
| `task_bulk_delete` | Preview or bulk delete tasks by IDs or filter | Yes |
| `task_complete` | Mark a task as complete | Yes |
### Agents
| Tool | Description | Mutates |
|------|-------------|---------|
| `agent_list` | List user-visible agent aliases and capabilities | No |
| `agent_get` | Get an agent alias by slug or ID | No |
| `agent_create` | Create an agent alias | Yes |
| `agent_update` | Update alias metadata, capabilities, or permissions | Yes |
| `agent_disable` | Disable an alias without deleting history | Yes |
| `agent_work_list` | List executable work assigned to an alias | No |
### Work Items
| Tool | Description | Mutates |
|------|-------------|---------|
| `work_item_list` | List work items with authoritative dependency claimability | No |
| `work_item_get` | Get work details, dependencies, satisfaction, and claimability | No |
| `work_item_create` | Create bounded work with optional UUID `dependsOn` edges | Yes |
| `work_item_dependencies_replace` | Atomically replace a work item's UUID dependencies | Yes |
| `work_item_claim` | Claim queued executable work with a lease | Yes |
| `work_dependency_policy_get` | Get a project's default dependency gate | No |
| `work_dependency_policy_update` | Set a project's default dependency gate | Yes |
| `work_item_start` | Mark claimed work running | Yes |
| `work_item_heartbeat` | Extend a lease | Yes |
| `work_item_block` | Mark work blocked | Yes |
| `work_item_review` | Mark work as needing review | Yes |
| `work_item_complete` | Complete work with summary/artifacts | Yes |
| `work_item_fail` | Mark work failed | Yes |
| `work_item_release` | Release work back to the queue | Yes |
| `work_item_cancel` | Cancel work | Yes |
### Knowledge / Notes
| Tool | Description | Mutates |
|------|-------------|---------|
| `note_list` | List notes with type, project, archive, and title filters | No |
| `note_get` | Get a single note with full content | No |
| `note_search` | Semantic search across knowledge base | No |
| `note_create` | Create a new note (markdown) | Yes |
| `note_update` | Update note title, content, or type | Yes |
| `note_delete` | Delete a note (destructive) | Yes |
| `note_bulk_delete` | Preview or bulk delete notes by IDs or filter | Yes |
### People
| Tool | Description | Mutates |
|------|-------------|---------|
| `people_search` | Search contacts with fuzzy or exact/prefix filters | No |
| `person_create` | Create a contact | Yes |
| `person_update` | Update a contact | Yes |
| `person_delete` | Delete a contact (destructive) | Yes |
| `people_bulk_delete` | Preview or bulk delete contacts by IDs or filter | Yes |
| `person_enrichment_availability` | Check identity readiness and current app prices without dispatching providers | No |
| `person_enrichment_run` | Run paid, idempotent app-equivalent enrichment and return stored proposals and billing evidence | Yes |
| `person_enrichment_apply` | Apply selected stored profile fields and facts from a settled run; not retry-safe | Yes |
### Organizations
| Tool | Description | Mutates |
|------|-------------|---------|
| `organization_search` | Search organizations with fuzzy or exact/prefix filters | No |
| `organization_create` | Create an organization | Yes |
| `organization_update` | Update an organization | Yes |
| `organization_delete` | Delete an organization (destructive) | Yes |
| `organization_bulk_delete` | Preview or bulk delete organizations by IDs or filter | Yes |
| `organization_enrichment_availability` | Check provider availability and current app prices without dispatching providers | No |
| `organization_enrichment_preview` | Run the paid, idempotent app preview and save evidence without canonical CRM writes | Yes |
### Lead Discovery
| Tool | Description | Mutates |
|------|-------------|---------|
| `lead_discovery_company_search` | Run one bounded paid company search and stage source-backed review candidates | Yes |
| `lead_discovery_candidate_list` | List candidates and their CRM match/review state | No |
| `lead_discovery_candidate_review` | Shortlist or reject one candidate with a recorded reason | Yes |
| `lead_discovery_import_plan_create` | Create a durable CRM import plan from shortlisted candidates; approval and apply remain separate | Yes |
See [Headless CRM import plans](../../docs/crm/headless-import-plans.md) for the
approval and apply lifecycle shared by CLI and MCP.
### Calendar
| Tool | Description | Mutates |
|------|-------------|---------|
| `calendar_list_events` | List calendar events for a date range | No |
| `calendar_create_event` | Create a new calendar event | Yes |
| `calendar_update_event` | Update a calendar event | Yes |
| `calendar_delete_event` | Delete a calendar event (destructive) | Yes |
### Local Source Context
| Tool | Description | Mutates |
|------|-------------|---------|
| `git_blame_symbol` | Run git blame on a local file range | No |
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
| Tool | Description | Mutates |
|------|-------------|---------|
| `code_memory_store` | Store a curated code fact | Yes |
| `code_memory_search` | Search stored code facts | No |
| `code_memory_list` | List all stored code memories | No |
| `code_memory_delete` | Delete a code memory (destructive) | Yes |
### Vault / Secrets
| Tool | Description | Mutates |
|------|-------------|---------|
| `vault_list` | List vault entries (metadata only) | No |
| `vault_create` | Store a new encrypted secret | Yes |
| `vault_update` | Update vault entry metadata | Yes |
| `vault_search` | Search vault entries by name/description | No |
| `vault_audit` | Inspect the Vault audit trail | No |
| `vault_materialization_request` | Request approval for one exact materialization destination | Yes |
| `vault_materialization_status` | Check materialization status without returning secret bytes | No |
| `capability_list` | List governed Vault execution capabilities | No |
| `capability_describe` | Describe a governed Vault execution capability | No |
| `capability_execute` | Execute a governed capability without exposing secret bytes | Yes |
`vault_read` is retired. MCP never returns plaintext secret bytes; use a governed capability or an explicitly approved materialization instead.
### Entity Graph
| Tool | Description | Mutates |
|------|-------------|---------|
| `entity_graph` | Traverse the entity relationship graph | No |
| `schema_introspect` | Discover the full data model and entity types | No |
### Document Upload
| Tool | Description | Mutates |
|------|-------------|---------|
| `upload_document` | Upload a PDF, Markdown, or text file into Knowledge | Yes |
### Datasets (feature flag: `DATASETS_ENABLED=true`)
| Tool | Description | Mutates |
|------|-------------|---------|
| `dataset_list` | List datasets | No |
| `dataset_create` | Create a dataset | Yes |
| `dataset_query` | Query records by filters/sorts | No |
| `dataset_mutate` | Create/update/delete records (destructive) | Yes |
| `dataset_schema_modify` | Add/update/delete fields (destructive) | Yes |
| `dataset_summarize` | Summarize schema and sample rows | No |
| `dataset_facets` | Value distributions for fields | No |
| `dataset_quality_check` | Missing-value metrics, invalid values, uniqueness issues, repeated-value observations | No |
| `dataset_aggregate` | Grouped metrics (count, avg, sum, etc.) | No |
| `dataset_bucket` | Bucket numeric/date fields into ranges | No |
| `dataset_rank` | Rank records by sorts or weighted formula | No |
| `dataset_analyze` | Generate natural-language insights | No |
| `dataset_compare` | Compare metrics across segments | No |
| `dataset_export` | Export records as CSV | No |
| `dataset_join_rows` | Self-join with alias-scoped fields | No |
| `dataset_compute_fields` | Compute derived columns (lag, diff, rolling) | No |
| `dataset_timeseries` | Time series analysis with transforms | No |
| `dataset_materialize_result` | Save derived result as a new dataset | Yes |
| `dataset_plot_result` | Validate chart payload from derived result | No |
### Ontology (feature flag: `DATASET_ONTOLOGY_ENABLED=true`)
| Tool | Description | Mutates |
|------|-------------|---------|
| `object_find` | Find objects by type and property filters | No |
| `object_links` | Traverse graph links for an object | No |
| `object_action_run` | Run a declarative action on an object (destructive) | Yes |
## 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
| Variable | Required | Description |
|----------|----------|-------------|
| `SIFT_API_URL` | Yes | Siftable API URL |
| `SIFT_PAT` | Yes | Personal Access Token |
Legacy `EXF_API_URL` and `EXF_PAT` remain supported for existing MCP configs.
## Development
```bash
# 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
| Scope | Description |
|-------|-------------|
| `mcp:*` | Core project, task, calendar, knowledge, and people operations |
| `projects:read` | Read project data |
| `projects:write` | Create/update projects |
| `tasks:read` | Read tasks |
| `tasks:write` | Create/update/complete tasks |
| `knowledge:read` | Search/read notes |
| `knowledge:write` | Create notes |
| `calendar:read` | View calendar/free slots |
| `calendar:write` | Create calendar events |
| `people:read` | Search/view contacts |
| `people:write` | Create/update contacts |
| `work:read` | Read executable work queues |
| `work:write` | Mutate executable work queues |
| `lead_discovery:read` | Read lead-discovery runs and candidates |
| `lead_discovery:write` | Dispatch paid searches and review/import candidates |
| `vault:metadata:read` | Read Vault metadata and materialization status |
| `vault:manage` | Create/update Vault metadata and request materializations |
| `vault:audit:read` | Read the Vault audit trail |
## 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