@siftable/mcp-server

Siftable MCP Server

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

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 so the user can approve additional requestable scopes such as work:read. A configured Authorization header selects static PAT mode; that token's scopes cannot be expanded by an OAuth challenge.

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.

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.

Quick Start

1. Create a Personal Access Token

• Go to Siftable → Settings → Developer → Access Tokens
• Click "Create Token"
• Name it (e.g., "Cursor MCP")
• 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.
• 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.

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

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

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	Null rates, duplicates, uniqueness violations	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:

• project_list — Lists projects to find the auth project
• project_get_context — Retrieves tasks, notes, and signals for the project
• 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:

• note_search — Searches the knowledge base for "deployment process"
• code_memory_search — Searches stored code facts for deployment-related memories
• 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

# 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
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"

• Check that your token starts with sift_pat_ or legacy exf_pat_
• Verify the token hasn't been revoked
• Check the token hasn't expired

Tools not appearing

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

License

MIT