# MCP tools reference

> For the complete documentation index, see [llms.txt](https://falconer.com/docs/llms.txt).

Review the Falconer MCP tools for documents, comments, navigation, permissions, and media.


Falconer MCP exposes tools your AI client can use to find, read, create, update, organize, and manage Falconer documents.

![Claude.ai connector settings showing Falconer MCP tool permissions](/docs/images/falconer-mcp-tool-permissions.png)

## Use Falconer knowledge and connected tools

`ask_falcon` answers questions from your workspace with citations. For an action or a structured result, your AI client can call a named MCP tool directly. In addition to the document tools below, the hosted server exposes tools for searching connected knowledge, code, pull requests, issues, people, meetings, and the user’s connected services. Available tools depend on your permissions, connections, and organization settings.

| Need | Direct tools to look for |
| --- | --- |
| Find connected knowledge | `document_search`, `meeting_notes_search`, `source_tree`, `people_search` |
| Explore engineering work | `code_search`, `code_tree`, `read_file`, `git_raw`, `github_pull_request_search`, `linear_issue_search` |
| Work with connected accounts | `list_integrations`, `gmail_search`, `calendar_list_events`, `calendar_find_free_time` |
| Take an action | `linear_create_issue`, `calendar_create_event`, `gmail_create_draft`, or the document tools below |

A tool is available only when the corresponding source, account, and permission are available to you. A Gmail draft is saved for your review and is not sent. Calendar changes can invite or notify attendees, so inspect the target account and event before calling them. Not every web-chat capability runs in an MCP client: browsing a page, running a coding environment, generating media, and work that depends on a live Falconer conversation stay in the web app.\
\
For example, ask your client to find a relevant document, read it, then use a targeted edit tool to update one section. For calendar changes or external actions, review the exact target and result in your client. `ask_falcon` remains a question-answering tool; it does not perform document edits on your behalf.

## Organization discovery

| Tool | What it does |
| --- | --- |
| `list_organizations` | Lists Falconer organizations available to the MCP connection. |

If only one organization is available, your client can usually omit `organizationId`. If multiple organizations are available, pass the selected `organizationId` on future Falconer tool calls.

## Settings, account and billing

| Tool | What it does |
| --- | --- |
| `read_settings` | Reads one settings scope: `user` (display name, model, thinking effort, notification preferences), `document` (a document or skill by uuid), `org` (name, description, defaults) or `account` (plan, credit balance and packs, auto-reload, trial state, seats, pricing, available offer, and the setup steps a new workspace still has open). Every key reports its value, allowed values and whether it is editable. |
| `edit_settings` | Changes settings in one scope. Owners can rename the organization and set its description (`org` scope) and change the plan (`account` scope): `plan: "trial"` starts the free Pro trial; `plan: "credits"` (pay as you go) opens a Stripe page that saves a card and authorizes automatic credit top-ups without charging anything now; `credits.purchase` buys a credit pack now; `plan: "pro"` opens a monthly seat subscription checkout and `"pro-annual"` a yearly one. Each returns a Stripe-hosted URL in the change detail. `credits.autoReload` changes the top-up pack and threshold, or turns top-ups off. Seats match workspace membership automatically. On a document (`document` scope) it sets status, labels, reviewers, appearance, auto-update and custom instructions; `type: "skill"` turns the document into an agent skill, whose `activation`, `contextKeys` and `description` can be set in the same call. |
| `create_billing_portal_session` | Returns a Stripe-hosted billing portal URL for managing the payment method, seats, and invoices. A workspace that has never been billed has no portal yet; to save a card without charging it, set `credits.autoReload` or `plan: "credits"` with `edit_settings`. |

For the first week, a new workspace's `account` scope lists the setup steps its owners still have open in the `onboarding` key: naming the workspace, connecting a source and choosing a plan. While a step is open, the server also offers an `onboard_workspace` prompt that walks your agent through them. `list_integrations` lists every source the workspace can connect, each with a link the person opens in their browser to sign in to the provider; when the flow finishes, the page tells them to go back to their agent. It also reports when a source still needs a step in Falconer (picking Jira or Asana projects, or Confluence spaces), with a link to that step, and the latest indexing run.

Connecting a brand-new account automatically creates its organization server-side, so no tool call is needed to sign up. The plans, seats and credit packs these tools expose are the same ones described in [Plans and billing](https://falconer.com/docs/plans-and-pricing/plans-and-billing.md) and [Buy credits and manage auto reload](https://falconer.com/docs/plans-and-pricing/buy-credits-and-auto-reload.md). Payment details are only ever entered on Stripe-hosted pages opened in a browser. Agents should never ask for card details in chat; after checkout, they read the `account` scope again to confirm the plan, purchase or auto-reload took effect. Auto-reload is only turned on when you agree to it: paying for a pack with auto-reload saves the card and authorizes Falconer to buy the same pack whenever your balance drops below the threshold you chose. Changes that need approval (for example sharing a document with someone new) are reported as `requires_confirmation` and have to be approved in the Falconer app.

## Find and read documents

| Tool | What it does |
| --- | --- |
| `search` | Searches Falconer documents by keyword query, semantic query, or both. |
| `read` | Reads a Falconer document by document ID, title, or Falconer URL. Given a file id or file URL, reads a file placed in the navigation instead, with a temporary download link. |

Use `search` when you do not know the exact document. Use `read` before editing so the agent can copy exact Markdown text from the current document.

## Create and update documents

| Tool | What it does |
| --- | --- |
| `create` | Creates a Falconer document from Markdown. |
| `replace_document_content` | Replaces exact Markdown text in a document. |
| `insert_document_content` | Inserts Markdown before or after exact anchor text, or at the start or end of a document. |
| `delete_document_content` | Deletes exact Markdown text from a document. |
| `edit` | Legacy exact replacement tool. Prefer the targeted content tools above. |
| `overwrite` | Replaces the full Markdown body of a document. |
| `delete` | Archives a Falconer document by ID, or deletes a file placed in the navigation by its file id or file URL. |

Prefer `replace_document_content`, `insert_document_content`, and `delete_document_content` for targeted updates. Use `overwrite` only when the whole document needs to be rewritten.

## Comments

| Tool | What it does |
| --- | --- |
| `list_document_comments` | Lists comment threads on a Falconer document. |
| `reply_to_comment` | Replies to an existing document comment. |
| `edit_comment` | Edits one of your existing comments. |
| `delete_comment` | Deletes one of your existing comments. |
| `resolve_comment` | Resolves a document comment thread. |
| `unresolve_comment` | Reopens a resolved document comment thread. |

## Navigation and folders

| Tool | What it does |
| --- | --- |
| `list_nav_children` | Lists visible child folders, documents, and files for a navigation location. |
| `get_nav_tree` | Gets a visible Falconer navigation tree. |
| `get_folder` | Gets folder metadata and visible one-level children. |
| `create_folder` | Creates a Falconer folder. |
| `update_folder` | Updates a folder title or description. |
| `reorder_folder_children` | Sets the full direct-child order for a folder. |
| `reorder_nav_children` | Sets the full direct-child order for a folder or document nav item. |
| `move_nav_item` | Moves a folder, document, or file navigation item. |
| `move_document` | Moves a document navigation placement by document ID. |
| `publish_document` | Publishes a private document into company navigation. |
| `delete_folder` | Archives a folder and its documents. |

Inspect navigation placement before moving documents or folders. If a document move or publish reports ambiguous placement, retry with the returned `sourceNavItemId`.

## Public docs sites

Tools for managing a space's [docs site](https://falconer.com/docs/public-docs/overview.md). Publishing, settings, passwords, and custom domains need an organization owner.

| Need | Tools |
| --- | --- |
| Sites and builds | `list_docs_sites`, `get_docs_site`, `create_docs_site`, `set_docs_subdomain`, `trigger_docs_build`, `list_docs_builds`, `get_docs_build`, `publish_docs_build`, `unpublish_docs_site`, `cancel_docs_build`, `delete_docs_build`, `retry_docs_build_index`, `request_docs_preview`, `get_docs_preview`, `get_docs_broken_links` |
| Settings and access | `get_docs_site_config`, `update_docs_site_config`, `get_docs_redirects`, `set_docs_redirects`, `set_docs_site_password`, `clear_docs_site_password`, `sign_out_docs_site_visitors` |
| Custom domain | `get_docs_custom_domain`, `set_docs_custom_domain`, `check_docs_custom_domain`, `activate_docs_custom_domain`, `disable_docs_custom_domain`, `remove_docs_custom_domain` |
| Site navigation | `get_docs_view`, `create_docs_view_page`, `create_docs_view_folder`, `update_docs_view_item`, `move_docs_view_items`, `reorder_docs_view_children`, `remove_docs_view_item` |
| Files behind the site | `list_file_view_files`, `read_file_view_file`, `write_file_view_file`, `create_file_view_page`, `create_file_view_directory`, `move_file_view_file`, `delete_file_view_file`, `publish_file_view_page`, `upload_file_view_file`, `get_file_view_download_url` |

`publish_docs_build` also rolls back when you pass an older build. `set_docs_redirects` replaces the whole list, so pass the list you read as `base` to merge your edits.

## Knowledge Health

Tools for reading and triaging your organization’s [Knowledge Health](https://falconer.com/docs/knowledge-health/find-issues/work-from-slack-and-mcp.md) findings from an MCP client.

| Tool | What it does |
| --- | --- |
| `list_knowledge_health_findings` | Lists your organization’s open findings for one category, optionally filtered by severity. Returns 20 findings per page by default (up to 50), with `nextOffset` for the next page. |
| `update_knowledge_health_finding` | Updates a finding by its key: set `status` to `resolved` or `ignored`, assign an owner with `ownerEmail`, or pass `ownerEmail: null` to clear the owner. |

Call `list_knowledge_health_findings` first to get each finding’s key, then pass that key to `update_knowledge_health_finding`.

## Permissions and media

| Tool | What it does |
| --- | --- |
| `update_document_permissions` | Updates document ACL mode, organization-wide access, public access, user access, or group access. Direct permission changes on inherited documents switch them to explicit mode automatically. |
| `upload_media` | Uploads an image, video, or file attachment (PDF, Office, text, and code files) sent as base64 in the tool call and returns a snippet that can be inserted into document content. Pass `placement` to also place the file in the navigation. Best for small files or clients that cannot make HTTP requests. |
| `create_upload` | Starts an upload of any supported size and returns a short-lived URL that the client sends the raw file bytes to, so the file never passes through the conversation. |
| `complete_upload` | Finishes an upload started with `create_upload` and returns the same snippet as `upload_media`, plus the file's navigation placement when it was placed. |

By default an upload is an attachment: it only exists inside the documents that insert its snippet. Pass `placement: "library"` to also place a PDF, Office, image, or video file in the navigation, in the user's Artifacts folder or under `libraryFolder` as Artifacts > Subfolder, which is where agents should file documents' companion files. Pass `placement: "navigation"` with `parentFolderId` only when the user names a folder or Space. A placed file is listed by `list_nav_children` and `get_nav_tree` as a `file` item, moved with `move_nav_item`, read with `read`, and deleted with `delete`, all by its file id. A sibling that already holds the name is numbered around unless `replace` is set, which hands the new bytes to the existing file so its id and links stay valid.

## Permissions

The MCP connection uses the permissions of the authenticated Falconer user or organization bot. Your client can only access documents, folders, comments, and permissions that identity can access in Falconer.