@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.27 compatibility note

The dataset_create, dataset_mutate, dataset_schema_modify, and dataset_materialize_result tools now 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 scopes: mcp:* (or specific scopes like projects:read, tasks:write)
• 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

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
task_link_code	Link a task to a code file/commit	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

Codebase Indexing

Tool	Description	Mutates
codebase_list	List indexed repositories	No
codebase_register	Register a new repository for indexing	Yes
codebase_status	Check indexing status and stats	No
codebase_snapshot_status	Get latest index snapshot for a repository	No
codebase_materialize_snapshot	Download a snapshot archive	No
codebase_index	Full index: scan and upload all files	Yes
codebase_index_incremental	Incremental index: git-aware, changed files only	Yes
codebase_delete	Delete a repository and all indexed data (destructive)	Yes

Code History & Expertise

Tool	Description	Mutates
code_who_knows	Find experts for a code area	No
code_compute_expertise	Refresh the expertise index	Yes
code_history	Get commit history for a repository	No
git_blame_symbol	Run git blame on a local file range	No

Code Memories

Tool	Description	Mutates
code_memory_store	Store a fact about the codebase	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