ctlsurf
Server Details
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
- Status
- Healthy
- Uptime
- 100.0% over the last 24 hours
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- ChatGPT
- –
- Claude
- –
TDQS
Scored across 54 tools
Several discovery/lookup tools overlap in purpose: list_pages vs search_pages vs find_linkable_pages vs get_page_tree, and search_folder vs find_folder_by_path vs get_folder vs list_folders. Detailed descriptions often clarify preferred usage (e.g., get_image vs get_image_url), but with 54 tools several boundaries still require careful reading.
Nearly all tools follow a snake_case verb_noun pattern: create_page, update_block, list_tickets, delete_folder, restore_page. Minor outliers like ctlsurf_call and permanent_delete_page remain readable and consistent with the overall convention.
54 directly listed tools is very heavy for a page/block/project workspace, even though deferred toolsets reduce some specialty areas. The breadth reflects many domains, but the initial tool surface is large enough to burden agents.
The surface covers lifecycle operations for pages, blocks, folders, tickets, tasks, files, links, history, trash, and archiving, plus deferred specialty toolsets. Minor gaps remain, such as no direct create_folder (folders are auto-created via create_page) and no delete_ticket tool.
Publisher details
- Operator
- Phenx AI · Publisher source
- Operator website
- https://www.phenx.ai/ · Publisher source
- Vendor relationship
- Not applicable
- Documentation
- https://ctlsurf.com/docs · Publisher source
- Privacy policy
- Not provided
- Trust center
- https://ctlsurf.com/privacy · Publisher source
- Restrictions
- Free For trying it on one project. $0 / month The full workspace, smaller limits 5 projects · 500 MB storage MCP access for your agents 1 Worker, a terminal on your machine you drive from the browser Get started free ↗ Pro For running several projects at once. $15 / month Introductory price 20 projects · 10 GB storage Version history on everything but live data tables 3 Workers Explore Pro ↗ Business For a team sharing one workspace. $20 / seat / month Assign seats to your team 30 projects · 15 GB per seat Shared organization workspace Roles and usage controls · Publisher source
Available Tools
54 toolsadd_checklist_itemCInspect
Add an item to a checklist block
Inputs: text (required), block_id (required), done.
add_ctlsurf_task_itemBInspect
Add a new task to a ctlsurf_task block. Use this to create work items for yourself.
Example: add_ctlsurf_task_item(block_id="<block_id>", text="Implement user authentication with JWT") add_ctlsurf_task_item(block_id="<block_id>", text="Debug API endpoint", skill_id="<skill_id>")
Inputs: text (required), block_id (required), done, notes, +1 more.
archive_folderAInspect
Archive a folder. Archived folders are hidden by default and don't count toward your project quota.
Inputs: folder_id (required).
archive_groupAInspect
Archive a whole folder group: every active project in it is archived at once. Nothing is deleted; the group's dashboard stays readable, and restore_group brings all the projects back. Confirm with the user first.
Inputs: group (required).
confirm_uploadAInspect
Confirm a completed file upload and create the database record.
Call this after successfully uploading a file to the presigned URL from get_upload_url. This verifies the file exists in storage and creates a file block on the page.
Inputs: s3_key (required), file_id (required), page_id (required), filename (required), +2 more.
create_blockAInspect
Create a new block on a page. Block types and their props:
text: Rich markdown content. Props: {"content": "markdown text"}
checklist: Task list with checkboxes. Props: {"items": [{"id": "item-0", "text": "Task", "done": false}]} or use add_checklist_item after creation
ctlsurf_task: Agent task assignments with notes. Props: {"items": [{"id": "task-0", "text": "Task", "done": false, "notes": []}]} or use add_ctlsurf_task_item after creation
table: Structured data grid. Props: {"columns": ["Col1", "Col2"], "rows": [["val1", "val2"]]}
tree: Hierarchical tree display. Props: {"nodes": [{"id": "1", "label": "Root", "children": [{"id": "2", "label": "Child"}]}]}
react_flow: Interactive node graph (auto-creates Graph). Props: {"graph_id": "uuid"} or empty to auto-create
page_summary: Page metadata for organization. Props: {"summary": "...", "purpose": "...", "status": "active", "tags": [], "key_topics": []}
file: File/image attachment. Props: {"file_id": "uuid", "filename": "name.ext", "mime_type": "image/png", "size_bytes": 12345}. To upload, use get_upload_url + curl PUT + confirm_upload — this creates the file block for you.
mindmap: Interactive mind map with visual editor. Props: {"content": "..."} where content can be:
Option 1 - Markdown format (recommended for agents):
# Central Topic ## Branch 1 - Leaf item A - Leaf item B ## Branch 2 ### Sub-branch - [[Linked Page|page-uuid]]Use # for root, ## for branches, ### for sub-branches, - for leaf items. Link to pages with [[Display Text|page-uuid]] syntax.
Option 2 - JSON tree format:
{"id": "root", "text": "Central Topic", "children": [ {"id": "b1", "text": "Branch 1", "children": [ {"id": "l1", "text": "Leaf", "children": [], "link": "/page/uuid"} ]} ]}
Dataspace blocks (dataspace pages only — use dedicated tools instead of create_block):
datastore: (dataspace pages only) Structured data table with typed columns and row-level operations. Use
create_datastoretool instead.state: (dataspace pages only) Key-value store for agent config, counters, flags. Props: {"data": {"key": "value"}}. Use
get_state/set_statetools.log: (dataspace pages only) Append-only timestamped event stream. Props: {"entries": [], "max_entries": 1000}. Use
append_log/query_logtools.
These block types can ONLY be created on pages with type="dataspace" (e.g., the "Agent Datastore" page under your project root).
presentation: Slide deck (960x540 canvas, .pptx export). Use the
create_presentationtool, thenadd_slide_from_template/add_structured_slidefor rich structured slides. Markdowncontentslides render as flat text (no tables/bold/links) — avoid for real decks. Props: {"slides": [...], "config": {"theme": "dark"}}.swimlane: Project timeline: tasks in lanes with start/due dates, progress, status and dependencies, shown with a today line and overdue flags. Use
load_toolset(toolset="swimlanes")thencreate_swimlane/add_swimlane_task; tasks are not stored in props.visual: Explanatory graphic (steps, flow, compare, stats, bars, callout, tokens, cycle, funnel). Prefer it over long lists when explaining; use
load_toolset(toolset="visuals")thencreate_visual.
Use checklist for simple task lists, ctlsurf_task for agent-assigned work with progress notes.
Tickets are not blocks: to create a ticket use create_ticket. Agents cannot add text, checklist, task or other non-dataspace blocks to a project's Tickets page.
Inputs: type (required), page_id (required), props, title.
create_pageAInspect
Create a new page. The page is automatically assigned to a folder based on:
Explicit folder_id (if provided)
Parent page's folder (if parent_id provided)
Working directory (if cwd provided) - auto-creates folder if needed
For a project with an organization template, first call get_project_organization(project_root_id). Choose a section using its purpose and the page content, then pass organization_placement: {mode: "section", project_root_id: "...", expected_binding_revision: 1, section_key: "..."} Omit parent_id: core resolves the section and creates only missing section pages on that path. To reuse an existing section page, explicitly include it in anchor_page_ids. Only if the user requests an exception, use mode: "user_override" with their reason and a parent_id inside the same project (omit parent_id to use the project root). This workflow makes no server-side LLM call. Placement is the agent's decision.
IMPORTANT: For root pages (no parent_id), this tool automatically checks if a page already exists with the same root_path or repo_url. If found, it returns the existing page instead of creating a duplicate.
Example - simple page creation with auto-folder: create_page(title="Bug Notes", cwd="/path/to/project") -> Creates page, auto-creates "project" folder if needed
Example - sub-page (inherits folder from parent): create_page(title="API Docs", parent_id="<parent_page_id>")
Explaining something on the page? Add visuals too: load_toolset(toolset="visuals").
Inputs: title (required), cwd, tags, type, +5 more.
create_page_linkAInspect
Create a properly formatted page link for use in markdown content.
Returns the wiki-style link format: [[Display Text|page_uuid]]
Use this to generate links when creating or updating text blocks. The link format ensures the link remains valid even if the page is renamed.
Example: create_page_link(page_id="abc-123", display_text="Architecture Overview") -> Returns: {"link": "[[Architecture Overview|abc-123]]", ...}
If display_text is not provided, the page's current title will be used.
Usage in text block: update_block(block_id, props={"content": "See the " + link + " for details."})
Inputs: page_id (required), display_text.
create_ticketAInspect
Create a ticket in a project. Use this whenever the user asks you to create, file, log or record a ticket (bug, backlog item, follow-up, feature request) for a project.
A ticket is a row in the project's "Tickets" datastore (columns Title, Description, Status, Priority, Created) on the project's protected Tickets page. This tool finds that page from any page in the project and creates the datastore with the standard columns if it does not exist yet.
Never write a ticket as a text, checklist or task block on the Tickets page: agents are rejected there, and such blocks do not appear in the ticket views.
Not for: items on the Agent Tasks list (add_ctlsurf_task_item), or Business change orders / proposals / SOWs (dashboard cards, load_toolset("dashboards")).
Put the full ticket body (problem, scope, acceptance criteria, links) in description as markdown.
Example: create_ticket(page_id="", title="Retry failed uploads", description="## Problem\n...", priority="High")
Inputs: title (required), page_id (required), status, priority, +1 more.
ctlsurf_callAInspect
Invoke a ctlsurf tool from a deferred toolset by name. Use load_toolset first to get the tool's documentation and input schema, then pass its name and arguments here. Listed tools can also be invoked this way, but calling them directly is preferred.
Inputs: tool_name (required), arguments.
delete_blockBInspect
Delete a block from a page
Inputs: block_id (required).
delete_folderAInspect
Delete a folder. Pages in the folder will be moved to root level.
Inputs: folder_id (required).
delete_pageBInspect
Delete a page and all its blocks
Inputs: page_id (required).
find_folder_by_pathBInspect
Find a folder by its codebase root path
Inputs: root_path (required).
find_linkable_pagesAInspect
Search for pages to link to.
Use this before creating links to find the right page. Returns pages matching the search query with their IDs for use with create_page_link.
Examples: find_linkable_pages(query="architecture") -> Search by title find_linkable_pages(folder_id="...") -> List pages in folder find_linkable_pages(query="api", limit=5) -> Limit results
Inputs: limit, query, folder_id.
find_page_by_root_pathAInspect
Find a control plane page for a codebase. Use this to locate your project's page on session start.
Examples:
find_page_by_root_path(repo_url="https://github.com/user/repo") - by repo URL (preferred, cross-machine)
find_page_by_root_path(root_path="/path/to/project") - by local path (auto-detects repo URL)
Returns matching pages with match_type: "repo_match" (preferred), "exact" (path match), or "parent" (subdirectory).
Inputs: repo_url, root_path.
get_backlinksAInspect
Get all pages that link to a specific page.
Returns the source page title, block ID, and link text for each incoming link. Use this to understand how pages are connected and discover related content.
Example: get_backlinks(page_id="abc-123") -> Returns list of pages that contain [[...|abc-123]] links
Inputs: page_id (required).
get_block_historyAInspect
Get version history for a block. Shows previous versions that can be restored.
Inputs: block_id (required).
get_block_sliceAInspect
Fetch a slice of a block's content (for large blocks). Returns paging metadata. Use offset/limit to paginate through large blocks.
Inputs: block_id (required), limit, offset.
get_ctlsurf_instructionsAInspect
Initialize a project with ctlsurf or get ctlsurf integration instructions.
Use this when the user says "initialize project with ctlsurf" or "set up ctlsurf for this project".
Returns instructions to add to your project memory/config file (CLAUDE.md, AGENTS.md, .cursorrules, etc.):
ctlsurf as source of truth
Checking pending tasks on session start
Documenting assumptions, shortcuts, decisions
Task workflow (claim, progress, complete, follow-up)
Block types guide (text, checklist, table, tree, react_flow, ctlsurf_task, datastore, state, log)
When to update documentation
Usage:
Detect the git remote URL: run
git remote get-url originDetect the hostname: run
hostnameCall this tool with root_path, repo_url, and hostname
If the result has needs_project_choice=true, this checkout (e.g. a fresh clone on a new machine, or a teammate's clone) matches existing projects for the same repo. Show the user the candidates and ASK which project to link it to, then call again with folder_id=; if they want a separate project, call again with create_new=true.
Add the returned 'instructions' to your project memory/config file
A project can live on many machines: each checkout (machine + path) is added to the project's machine list, so several people on several machines share one project.
Examples:
get_ctlsurf_instructions(root_path="/path/to/project", repo_url="https://github.com/user/repo", hostname="macbook-pro")
get_ctlsurf_instructions(root_path="/path/to/project", repo_url="...", hostname="...", folder_id="")
get_ctlsurf_instructions(root_path="/path/to/project", format="text")
Inputs: root_path (required), format, hostname, repo_url, +2 more.
get_file_textAInspect
Get text content from a text-based file (txt, md, json, etc.).
Inputs: file_id (required).
get_folderAInspect
Get a folder by ID with its pages
Inputs: folder_id (required).
get_imageAInspect
Get an image as base64 data for vision model analysis. Returns base64-encoded image + metadata.
IMPORTANT: Only use this when you need to ANALYZE image content (e.g., read a chart, describe a screenshot, extract text from an image). This sends the full image data through MCP which is expensive for large images.
For all other cases, use get_image_url instead — it returns a lightweight presigned URL.
Inputs: file_id (required).
get_image_urlAInspect
Get a temporary presigned URL for an image/file. The URL is valid for 1 hour, requires no authentication, and costs almost zero tokens.
Use this as your DEFAULT way to access images. Use cases:
View/check what an image looks like (open the URL)
Reference in presentations, markdown, or HTML:
or
Share with users or embed in documentation
Check image metadata (dimensions, size, type)
Only use get_image instead when you need to ANALYZE image content with vision (e.g., read a chart, OCR text from a screenshot).
Inputs: file_id (required).
get_outlinksAInspect
Get all pages that a specific page links to.
Returns the target page title, block ID, and link text for each outgoing link.
Example: get_outlinks(page_id="abc-123") -> Returns list of pages linked from page abc-123
Inputs: page_id (required).
get_page_summaryBInspect
Get the page summary block for a page. Returns summary, purpose, status, tags, key topics.
Inputs: page_id (required).
get_page_treeAInspect
Get the hierarchical tree structure of all pages
Inputs: no named parameters.
get_pending_agent_tasksAInspect
Get all pending ctlsurf_task items assigned to you. Call this on session start to check for work.
Examples:
get_pending_agent_tasks(repo_url="https://github.com/user/repo") - by repo URL (preferred)
get_pending_agent_tasks(root_path="/path/to/project") - by local path (auto-detects repo URL)
get_pending_agent_tasks() - get ALL pending tasks across all projects
Tasks may include a skill (playbook) with workflow steps and guards to follow.
Inputs: repo_url, root_path.
get_project_organizationAInspect
Read a project's versioned filing structure before creating a page: section keys, purposes, paths, examples, rules and existing section-page IDs. Choose placement yourself from the page content. Pass the chosen section and returned binding revision in create_page.organization_placement. When the user explicitly requests another location, use mode=user_override with their reason. Core validates permissions/project boundaries; no server-side LLM or semantic verdict is involved.
Inputs: project_root_id (required).
get_upload_urlAInspect
Get a presigned URL for direct file upload. This avoids sending file data through MCP, saving tokens.
Flow:
Call get_upload_url(page_id, filename, mime_type) → returns upload_url, file_id, s3_key
Use Bash to upload: curl -X PUT -H 'Content-Type: <mime_type>' --upload-file /path/to/file '<upload_url>'
Call confirm_upload(file_id, s3_key, filename, mime_type, page_id) → creates file record and block
The upload_url expires in 15 minutes. Supported types: images (png, jpg, gif, webp), PDFs, Office docs, text files, and email exports (.eml, .emlx, .msg, .mbox). Use the returned mime_type for the PUT Content-Type header and confirm_upload.
Inputs: page_id (required), filename (required), mime_type (required).
list_blocksBInspect
List all blocks for a specific page
Inputs: page_id (required).
list_blocks_metaAInspect
List lightweight block metadata (no props) for a page, including size hints. Use this to discover blocks without pulling full content.
Inputs: page_id (required).
list_foldersAInspect
List all folders (codebase workspaces). Returns folder metadata only by default. Use include_pages=true to get nested page trees (warning: can be very large). Prefer get_folder(folder_id) for a single folder's pages.
Inputs: include_pages, include_archived.
list_page_filesAInspect
List all files/images attached to a page. Returns metadata for each file including id, filename, mime_type, size, and dimensions for images.
Inputs: page_id (required).
list_pagesAInspect
List owned, enterprise-managed and shared pages. Active Business owners have full control within enterprise projects; ordinary shares do not reveal private pages. Returns slim metadata by default. Use folder_id to filter by project and include_shared=false to omit ordinary shared pages.
Inputs: slim, folder_id, include_shared.
list_ticketsAInspect
List a project's tickets (rows of its Tickets datastore), open work first, newest first. Done tickets are hidden unless include_done=true or status includes "Done".
Descriptions are cut to a 300-character preview unless full_descriptions=true. Each ticket has a ticket_id for update_ticket.
Inputs: page_id (required), limit, status, include_done, +1 more.
list_trashAInspect
List all deleted pages in the trash. Deleted pages can be restored.
Inputs: no named parameters.
load_toolsetAInspect
Load the documentation and input schemas for a deferred toolset. Most ctlsurf tools are listed directly, but specialty toolsets are deferred to keep the tool list small. Call this when you need one of them, then invoke the returned tools via ctlsurf_call(tool_name, arguments).
Available toolsets:
dashboards (18 tools): Business: group dashboards with change-order, proposal/SOW and ticket cards, documents, rollups and pinned live blocks
datastore (14 tools): Agent working data: typed-column data tables with row operations, key-value state blocks, append-only logs
graphs (12 tools): Diagrams: react-flow node graphs, ER diagrams (DB schemas, API contracts, domain models), tree nodes
presentations (7 tools): Slide decks: create presentations, add structured slides from templates, export to .pptx
skills (17 tools): Agent playbooks: create, search, fork and share reusable workflow definitions
swimlanes (5 tools): Project timelines: swim-lane blocks with tasks in lanes, start/due dates, progress, status and dependencies
visuals (3 tools): Explanatory graphics for pages: steps, flows, comparisons, stats, bars, callouts, token strips, cycles, funnels. Use whenever a page explains something
Inputs: toolset (required).
permanent_delete_pageAInspect
Permanently delete a page. This cannot be undone!
Inputs: page_id (required).
restore_block_versionCInspect
Restore a block to a previous version.
Inputs: block_id (required), version_number (required).
restore_folderAInspect
Restore an archived folder back to active status.
Inputs: folder_id (required).
restore_groupAInspect
Restore every archived project in a folder group, undoing archive_group.
Inputs: group (required).
restore_pageAInspect
Restore a deleted page from trash.
Inputs: page_id (required).
search_blocksAInspect
Search block content and return snippets. Use get_block_slice for full content after finding matches.
Inputs: query (required), limit, offset, page_id.
search_folderAInspect
Search for a folder by path, git URL, or name.
Examples:
search_folder(query="https://github.com/user/repo", type="url") - by git repository URL
search_folder(query="/path/to/project", type="path") - by local filesystem path
search_folder(query="myproject", type="name") - by folder name (partial match)
Returns the matching folder(s) with match_type indicator.
Inputs: type (required), query (required).
search_pagesBInspect
Search pages by title using full-text search with fuzzy matching. Supports stemming (run/running/ran match) and typo tolerance (threshold 0.3).
Inputs: query (required), limit, offset, folder_id, +1 more.
update_blockCInspect
Update a block's properties, title, or order
Inputs: block_id (required), order, props, title.
update_checklist_itemCInspect
Update a checklist item
Inputs: item_id (required), block_id (required), done, text.
update_ctlsurf_task_itemAInspect
Update a ctlsurf_task item. Use to add progress notes, mark complete, or reopen with feedback.
Examples:
Add progress note: update_ctlsurf_task_item(block_id, item_id, notes=["Implemented login endpoint"])
Mark complete with structured completion (REQUIRED when done=true): update_ctlsurf_task_item( block_id="...", item_id="...", done=true, completion={ "summary": "Implemented user authentication with JWT", "assumptions": ["Database schema already supports user sessions"], "attempted_but_failed": ["Tried OAuth but API rate limited"], "simplified_or_skipped": [] } )
Reopen a completed task with feedback: update_ctlsurf_task_item( block_id="...", item_id="...", done=false, reopen_feedback="Please implement the rate limiting properly, don't skip it" )
Attach skill: update_ctlsurf_task_item(block_id, item_id, skill_id="<skill_id>")
IMPORTANT: When marking done=true, the completion object is REQUIRED with structured documentation of what was done, assumptions made, and any simplifications.
Inputs: item_id (required), block_id (required), done, text, +4 more.
update_folderBInspect
Update a folder's name, root_path, git_remote, hostname, or group
Inputs: folder_id (required), name, group, hostname, +2 more.
update_pageAInspect
Update a page's properties. Use this to link pages to codebases.
Examples:
update_page(page_id, repo_url="https://github.com/user/repo") - set repo URL for cross-machine support
update_page(page_id, root_path="/path/to/project") - set local path
update_page(page_id, title="New Title") - rename page
update_page(page_id, parent_id="<other_page_id>") - move under another page
update_page(page_id, folder_id="<folder_id>") - assign to a folder
update_page(page_id, tags=["architecture", "documentation"]) - set page tags
Inputs: page_id (required), tags, title, repo_url, +3 more.
update_page_summaryCInspect
Create or update a page's summary block with metadata like summary, purpose, status, tags, and key topics.
Inputs: page_id (required), tags, status, purpose, +2 more.
update_ticketAInspect
Update a project ticket by ticket_id (from create_ticket or list_tickets): change its status, priority, title or description. Only the fields you pass change.
Example: update_ticket(ticket_id="...", status="In Progress")
Inputs: ticket_id (required), title, status, priority, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Shared MCP memory for AI agents: knowledge base, skills, todos and agent-to-agent handoffs.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceShared memory and orchestration for coding agents, enabling persistent knowledge, multi-agent coordination, and a canonical workflow across MCP-compatible AI clients.83-
- AlicenseAqualityBmaintenanceEnables an AI coding agent and developer to keep a shared live markdown record of goals, tasks, detours, ideas, and standing instructions across long sessions and context compression. It provides MCP tools and a dashboard to track progress, branch and merge detours, and maintain focus.31567 npm4PolyForm Noncommercial 1.0.0
- AlicenseNot gradedqualityAmaintenanceOpen-source, self-hosted database and workspace for AI agents. Its MCP server lets agents manage structured records, documents, files, reusable skills, and apps, with auditable Change Requests for writes.929MIT
- AlicenseNot gradedqualityCmaintenanceA machine-local, agent-writable knowledge base MCP server that lets coding agents autonomously record and retrieve hard-won operational facts, incidents, and corrections as markdown pages in a git repo, with provenance, talk pages, and search.1 npmMIT
Glama MCP Gateway
Add one secure layer between your agents and this server.