driftless logo driftless
// Documentation

MCP Documentation

Driftless exposes a live MCP (Model Context Protocol) endpoint at app.godriftless.ai/mcp. MCP is an open protocol that lets AI agents and other clients discover and invoke tools through a standard JSON-RPC interface. This page documents everything you need to connect your own MCP-compatible client to Driftless — no support call required.

Overview

Driftless uses the Streamable HTTP MCP transport. Every request is an HTTP POST carrying a JSON-RPC 2.0 envelope to a single endpoint. The server is stateless — it does not issue an Mcp-Session-Id, so each request is independent and you do not need to maintain session state between calls.

A typical session is three steps:

  1. Initialize — send an initialize request with your client info and supported protocol version. The server replies with its serverInfo (name: "driftless", version: "1.0.0") and capabilities.
  2. Initialized notification — send a notifications/initialized notification (no response expected) to complete the handshake.
  3. Call methods — send tools/list to discover tools or tools/call to invoke one.
Protocol version: 2025-03-26. JSON-RPC 2.0 request IDs are integers by default.

Authentication

Every request must include an x-api-key header holding a Driftless API key. Keys are prefixed drift_ (legacy mc_ keys are still accepted). The key authenticates the request and scopes it to your organization's data and your agent's configured permissions.

Obtaining an API key

  1. Sign in to the Driftless app at app.godriftless.ai.
  2. Open your agent / bot credentials settings.
  3. Generate a new API key and copy the drift_… value immediately — it is shown once.

Treat the key like a password. If a key is compromised, rotate it from the same settings page; revoked keys are rejected immediately.

Example: authenticated request

The x-api-key header is the only credential required:

curl -X POST https://app.godriftless.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Endpoint

URLhttps://app.godriftless.ai/mcp
MethodPOST only (other methods return 405)
Content-Typeapplication/json
Acceptapplication/json, text/event-stream
Authx-api-key: <drift_…> header
ProtocolJSON-RPC 2.0 over Streamable HTTP (MCP 2025-03-26)
SessionStateless — no Mcp-Session-Id returned or required

Available tools

The Driftless MCP server exposes 37 tools. Each tool below lists its name, description, parameters (with types and required flags), and return shape. Tool manifest captured from the live endpoint on 2026-08-18.

Quick reference

ToolDescription
get_assigned_tasksGet tasks assigned to the authenticated bot.
get_task_directiveGet the full directive for a specific task.
get_task_mediaGet media (images, videos, audio, PDFs) attached to a task.
update_task_statusUpdate the status of a task.
add_commentAdd a comment to a task.
list_projectsList all projects in the organization.
list_initiativesList all initiatives in the organization, optionally filtered by project.
list_tasksList tasks across a project or initiative.
get_taskGet full details for a specific task by ID.
get_initiativeGet full initiative details including PRD and Tech Spec sections.
get_projectGet full project details including members, settings, repository URL, and task prefix.
list_prd_sectionsList PRD sections for an initiative.
get_prd_sectionGet a single PRD section's full content with HTML and paired tech spec ID.
list_tech_spec_sectionsList Tech Spec sections for an initiative.
get_tech_spec_sectionGet a single Tech Spec section's full content with HTML and paired PRD section ID.
get_initiative_contentGet all PRD and Tech Spec sections for an initiative in one call.
create_taskCreate a new task with title, description, acceptance criteria, and optional project/initiative/assignee.
update_taskUpdate an existing task.
create_initiativeCreate a new initiative within a project.
update_initiativeUpdate an existing initiative.
create_prd_sectionAdd a PRD section to an initiative.
update_prd_sectionUpdate a PRD section's content.
create_tech_spec_sectionAdd a Tech Spec section to an initiative.
update_tech_spec_sectionUpdate a Tech Spec section's content.
delete_taskDelete a task by its human-readable ID (e.g.
delete_prd_sectionDelete a PRD section from an initiative.
delete_tech_spec_sectionDelete a tech spec section from an initiative.
delete_initiativeDelete an initiative by its ObjectId.
link_tasksCreate a link between two tasks.
unlink_tasksRemove a link from a task by link ID.
list_task_linksList all links on a given task, showing the link type, linked task ID, title, and link ObjectId (needed for unlink_tasks).
search_tasksSearch and filter tasks across the organization.
assemble_boot_contextAssemble the full boot context for an agent — loads manifest, task, project, and initiative data to produce a complete directive payload for
push_notificationPush a real-time event notification to connected agents.
get_pending_notificationsGet pending notifications for a reconnecting agent.
list_org_membersList all members of the authenticated agent's organization.
get_userResolve a single user by ObjectId or display name.

Tool reference

Every tool returns a standard MCP result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the tool's result; isError is true for application-level failures (authentication, authorization scope, not-found, validation). Individual tools do not declare output schemas — the return shape is the MCP content envelope described here.

get_assigned_tasks #

Get tasks assigned to the authenticated bot. Returns a summary table with task IDs, titles, statuses, and priorities.

Parameters

ParameterTypeRequiredDescription
statusstringoptionalComma-separated status filter (e.g. "backlog" or "todo,in-progress"). Defaults to "todo".

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_task_directive #

Get the full directive for a specific task. Includes description, acceptance criteria, project context, initiative info, linked tasks, and comments.

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175", "HBI-017")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_task_media #

Get media (images, videos, audio, PDFs) attached to a task. Returns an array of media objects each containing userMediaId, mediaType, fileName, caption, and a presigned download URL (1-hour expiry). Scope: projects.tasks:view — the agent can only access media for tasks in projects it has view access to.

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

update_task_status #

Update the status of a task. Follow the status workflow: backlog → todo → in-progress → blocked → user-testing → done. When starting work, move to "in-progress". When ready for automated validation, move to "blocked". When validation passes and ready for user verification, move to "user-testing". Only move to "done" after user confirms completion — do NOT skip directly to "done" from "in-progress" or "todo".

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175")
statusstring (enum)requiredNew status for the task Allowed: backlog, todo, in-progress, blocked, user-testing, done

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

add_comment #

Add a comment to a task. ALWAYS add a comment when you start working on a task, when you make progress, and when you complete or update a task. This provides a trail of your work for the user.

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175")
contentstringrequiredComment text to add

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

list_projects #

List all projects in the organization. Returns project names, slugs, and descriptions.

Parameters

This tool takes no parameters.

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

list_initiatives #

List all initiatives in the organization, optionally filtered by project.

Parameters

ParameterTypeRequiredDescription
projectSlugstringoptionalFilter by project slug (e.g. "mission-control")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

list_tasks #

List tasks across a project or initiative. Returns all tasks with filtering by project slug, initiative ID, and status.

Parameters

ParameterTypeRequiredDescription
projectSlugstringoptionalFilter by project slug (e.g. "mission-control")
initiativeIdstringoptionalFilter by initiative ObjectId
statusstringoptionalComma-separated status filter (e.g. "todo,in-progress")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_task #

Get full details for a specific task by ID. Returns title, description, acceptance criteria, status, assignee, initiative, comments, and linked tasks.

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175", "HBI-017")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_initiative #

Get full initiative details including PRD and Tech Spec sections. Supports lookup by ObjectId or name (case-insensitive partial match).

Parameters

ParameterTypeRequiredDescription
initiativeIdstringoptionalInitiative ObjectId
namestringoptionalInitiative name (case-insensitive partial match). Use when you don't have the ObjectId.

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_project #

Get full project details including members, settings, repository URL, and task prefix.

Parameters

ParameterTypeRequiredDescription
projectSlugstringrequiredProject slug (e.g. "mission-control")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

list_prd_sections #

List PRD sections for an initiative. Returns section IDs, content titles, and tech spec pairings.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_prd_section #

Get a single PRD section's full content with HTML and paired tech spec ID.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId
sectionIdstringrequiredPRD section ObjectId

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

list_tech_spec_sections #

List Tech Spec sections for an initiative. Returns section IDs, content titles, and PRD pairings.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_tech_spec_section #

Get a single Tech Spec section's full content with HTML and paired PRD section ID.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId
sectionIdstringrequiredTech Spec section ObjectId

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_initiative_content #

Get all PRD and Tech Spec sections for an initiative in one call. Returns full content with paired section IDs for cross-referencing.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

create_task #

Create a new task with title, description, acceptance criteria, and optional project/initiative/assignee. For acceptance criteria, Given/When/Then format is preferred but not required.

Parameters

ParameterTypeRequiredDescription
titlestringrequiredTask title (required)
projectSlugstringrequiredProject slug (required, e.g. "mission-control")
descriptionstringoptionalTask description (HTML)
acceptanceCriteriaSectionsarray of objectsoptionalStructured acceptance criteria sections (MC-644). Given/When/Then format is preferred for each section description, but freeform text is accepted.
initiativeIdstringoptionalInitiative ObjectId to assign task to
assigneeIdstringoptionalUser ObjectId to assign the task to
statusstringoptionalInitial status (defaults to "backlog"). Valid: backlog, todo, in-progress, blocked, user-testing, done
prioritystringoptionalPriority (defaults to "medium"). Valid: low, medium, high, critical
typestringoptionalTask type (defaults to "feature"). Valid: feature, bug, improvement, chore

acceptanceCriteriaSections[] properties

ParameterTypeRequiredDescription
idstringrequiredAC section id (e.g. "ac-1")
titlestringoptionalShort human-readable label for the AC section
descriptionstringoptionalFreeform description; Given/When/Then format preferred but not required
statusstring (enum)optionalnot-started (default) | in-progress | ready-to-test | passed | failed Allowed: not-started, in-progress, ready-to-test, passed, failed
testRefsarray of objectsoptionalTest references linked to this AC

testRefs[] properties

ParameterTypeRequiredDescription
typestringrequiredci-check | s3-log | playwright-video | pr | comment
refstringrequiredReference identifier (URL, S3 key, PR number, comment ID)
statusstringoptionalpass | fail | pending (default: pending)
testTypestringoptionalunit | integration | e2e | manual
timestampstringoptionalISO 8601 date string

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

update_task #

Update an existing task. Only provided fields are updated (partial update). For acceptance criteria, Given/When/Then format is preferred but not required.

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175")
titlestringoptionalNew title
descriptionstringoptionalNew description (HTML)
acceptanceCriteriaSectionsarray of objectsoptionalStructured acceptance criteria sections (MC-644). Given/When/Then format is preferred for each section description, but freeform text is accepted.
initiativeIdstringoptionalNew initiative ObjectId (pass "null" to clear)
assigneeIdstringoptionalNew assignee user ObjectId
prioritystringoptionalNew priority (low, medium, high, critical)
typestringoptionalNew type (feature, bug, improvement, chore)

acceptanceCriteriaSections[] properties

ParameterTypeRequiredDescription
idstringrequiredAC section id (e.g. "ac-1")
titlestringoptionalShort human-readable label for the AC section
descriptionstringoptionalFreeform description; Given/When/Then format preferred but not required
statusstring (enum)optionalnot-started (default) | in-progress | ready-to-test | passed | failed Allowed: not-started, in-progress, ready-to-test, passed, failed
testRefsarray of objectsoptionalTest references linked to this AC

testRefs[] properties

ParameterTypeRequiredDescription
typestringrequiredci-check | s3-log | playwright-video | pr | comment
refstringrequiredReference identifier (URL, S3 key, PR number, comment ID)
statusstringoptionalpass | fail | pending (default: pending)
testTypestringoptionalunit | integration | e2e | manual
timestampstringoptionalISO 8601 date string

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

create_initiative #

Create a new initiative within a project.

Parameters

ParameterTypeRequiredDescription
namestringrequiredInitiative name (required)
projectSlugstringrequiredProject slug (required, e.g. "mission-control")
descriptionstringoptionalInitiative description
statusstringoptionalInitial status (defaults to "planning"). Valid: planning, active, completed, archived

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

update_initiative #

Update an existing initiative. Only provided fields are updated (partial update).

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
namestringoptionalNew name
descriptionstringoptionalNew description
statusstringoptionalNew status (planning, active, completed, archived)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

create_prd_section #

Add a PRD section to an initiative. Auto-creates a paired empty Tech Spec section.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
contentstringrequiredPRD section content in HTML (required)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

update_prd_section #

Update a PRD section's content.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
sectionIdstringrequiredPRD section ObjectId (required)
contentstringrequiredNew content in HTML (required)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

create_tech_spec_section #

Add a Tech Spec section to an initiative. Optionally link to an existing PRD section.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
contentstringrequiredTech Spec section content in HTML (required)
prdSectionIdstringoptionalPRD section ObjectId to link this to (optional)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

update_tech_spec_section #

Update a Tech Spec section's content.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
sectionIdstringrequiredTech Spec section ObjectId (required)
contentstringrequiredNew content in HTML (required)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

delete_task #

Delete a task by its human-readable ID (e.g. MC-175). Uses soft delete — the task is marked as deleted but not removed from the database.

Parameters

ParameterTypeRequiredDescription
taskIdstringrequiredHuman-readable task ID (e.g. "MC-175")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

delete_prd_section #

Delete a PRD section from an initiative. By default, only the PRD section is deleted and the paired tech spec section is preserved. Set deletePaired to true to also remove the paired tech spec section.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
sectionIdstringrequiredPRD section ObjectId to delete (required)
deletePairedbooleanoptionalIf true, also delete the paired tech spec section. Default: false — only the PRD section is removed, paired tech spec is preserved.

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

delete_tech_spec_section #

Delete a tech spec section from an initiative. By default, only the tech spec section is deleted and the paired PRD section is preserved. Set deletePaired to true to also remove the paired PRD section.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId (required)
sectionIdstringrequiredTech Spec section ObjectId to delete (required)
deletePairedbooleanoptionalIf true, also delete the paired PRD section. Default: false — only the tech spec section is removed, paired PRD is preserved.

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

delete_initiative #

Delete an initiative by its ObjectId. Warning: this is a hard delete and removes the initiative permanently. Check for associated tasks before deleting.

Parameters

ParameterTypeRequiredDescription
initiativeIdstringrequiredInitiative ObjectId to delete (required)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

search_tasks #

Search and filter tasks across the organization. Supports full-text search across titles and descriptions, plus structured filters for project, initiative, status, assignee, priority, and type. Returns a concise summary with task IDs, titles, statuses, and priorities. Results are capped at 50 to avoid token blowout.

Parameters

ParameterTypeRequiredDescription
querystringoptionalFull-text search across task titles and descriptions (e.g. "billing", "auth bug")
projectSlugstringoptionalFilter by project slug (e.g. "mission-control")
initiativeIdstringoptionalFilter by initiative ObjectId
statusstringoptionalComma-separated statuses (e.g. "todo,in-progress" or "done")
assigneeIdstringoptionalFilter by assignee user ObjectId
prioritystringoptionalComma-separated priorities (e.g. "high,critical")
typestringoptionalComma-separated types (e.g. "bug,feature")
limitnumberoptionalMax results to return (default 50, max 100)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

assemble_boot_context #

Assemble the full boot context for an agent — loads manifest, task, project, and initiative data to produce a complete directive payload for booting a nanobot instance. Returns goal string, directive markdown, environment variables, scope tags, and full context metadata.

Parameters

ParameterTypeRequiredDescription
agentIdstringrequiredRegistered agent ObjectId
taskIdstringrequiredTask ID to assign (e.g. "MC-239" or ObjectId)

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

push_notification #

Push a real-time event notification to connected agents. Supports task status changes, comments, swarm status changes, and initiative updates. Events are delivered via WebSocket to online agents and queued via webhook for offline agents.

Parameters

ParameterTypeRequiredDescription
typestringrequiredEvent type: task:created, task:updated, task:status_changed, task:assigned, comment:added, run:status_changed, initiative:updated
organizationIdstringrequiredOrganization ID to scope the event
prioritystringoptionalPriority: low, normal, high, urgent (default: normal)
projectIdstringoptionalProject ID for project-scoped events
payloadobjectoptionalEvent payload with type-specific fields
targetAgentsarray of stringoptionalSpecific agent IDs to target (leave empty for broadcast)

payload properties

ParameterTypeRequiredDescription
taskIdstringoptional
titlestringoptional
statusstringoptional
oldStatusstringoptional
newStatusstringoptional
runIdstringoptional
commentIdstringoptional
authorstringoptional
contentstringoptional
assignedTostringoptional
initiativeIdstringoptional
namestringoptional

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_pending_notifications #

Get pending notifications for a reconnecting agent. Returns events that were queued while the agent was offline.

Parameters

ParameterTypeRequiredDescription
agentIdstringrequiredAgent ID to retrieve pending events for

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

list_org_members #

List all members of the authenticated agent's organization. Returns each member's ObjectId, name, email, and role.

Parameters

This tool takes no parameters.

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

get_user #

Resolve a single user by ObjectId or display name. Returns the user's ObjectId, name, email, and role within the organization.

Parameters

ParameterTypeRequiredDescription
userIdstringoptionalUser ObjectId (e.g. "6a0faec3d20b91d766ba179e")
namestringoptionalDisplay name to search for (e.g. "Rocky")

Returns — a standard MCP tool result: { content: [{ type: "text", text: string }, …], isError?: boolean }. The text payload carries the result described above; isError is true when the tool call failed at the application level (auth, scope, not-found, validation).

Connection examples

curl

Three requests: initialize, send the initialized notification, then call a tool.

# 1) Initialize the session (JSON-RPC 2.0)
curl -X POST https://app.godriftless.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

# 2) Notify the server initialization is complete (no response expected)
curl -X POST https://app.godriftless.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3) Call a tool — list tasks assigned to your bot
curl -X POST https://app.godriftless.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_assigned_tasks","arguments":{"status":"todo"}}}'

TypeScript / JavaScript (MCP SDK)

Use the official @modelcontextprotocol/sdk client with the Streamable HTTP transport. Install with npm install @modelcontextprotocol/sdk.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://app.godriftless.ai/mcp"),
  { requestInit: { headers: { "x-api-key": process.env.DRIFTLESS_API_KEY! } } }
);

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// Discover available tools
const { tools } = await client.listTools();
console.log(tools.length + " tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "get_assigned_tasks",
  arguments: { status: "todo" },
});
console.log(result.content);

Error handling

Errors come in two layers: HTTP-level errors (returned as plain JSON before JSON-RPC processing) and JSON-RPC errors (returned inside a normal 200 response with an error field).

JSON-RPC error codes

CodeMeaningWhen
-32700Parse errorInvalid JSON in the request body.
-32600Invalid RequestThe JSON is not a valid JSON-RPC 2.0 request object.
-32601Method not foundThe requested RPC method does not exist.
-32602Invalid paramsMethod parameters are missing or invalid.
-32603Internal errorInternal JSON-RPC error.

Example JSON-RPC error response (returned with HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

HTTP error responses

StatusCauseExample body
400Malformed JSON-RPC request{"errors":[{"msg":"Invalid request body"}]}
401Missing or unrecognized / revoked x-api-key{"errors":[{"msg":"Authentication failed"}]}
405Non-POST method{"errors":[{"msg":"Method not allowed. Use POST for MCP requests."}]}
429Rate limit exceeded{"error":"Rate limit exceeded"}
500Internal server error{"error":"Internal server error"}

Authentication failure (401)

Returned when the x-api-key header is missing or the key is invalid, revoked, or belongs to an inactive bot:

// header absent
{"errors":[{"msg":"Authentication required. Provide x-api-key header."}]}

// key invalid / revoked
{"errors":[{"msg":"Authentication failed"}]}

Rate limited (429)

Returned when the API key exceeds its request budget. Includes standard RateLimit-* headers and a Retry-After header (seconds until the next available slot):

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 58
Retry-After: 58

{"error":"Rate limit exceeded"}

Rate limits

Driftless enforces per-API-key rate limiting on its HTTP API. The platform's standard API limiter is 100 requests per minute per key. MCP requests authenticate with the same API key and are subject to platform rate limiting and abuse protection.

Limit100 requests / minute / API key
ScopePer API key (drives per-agent and per-organization budgets)
Response headersRateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
On exceedHTTP 429 with Retry-After header and body {"error":"Rate limit exceeded"}
Exact limits may vary by plan. If you need higher throughput for production agent workloads, contact support@godriftless.ai.
driftless logo driftless

Specs in, software out. Agentic spec-driven product delivery.

Product
Features Pricing Security Benchmarks Engineering BA Agent Orchestrator White Paper
Documentation
MCP API Reference
Legal
Terms Privacy SLA Cookies
Status
System Status agentic.ai — Agenticness 14/36

© 2026 Driftless. All rights reserved.