MCP Server

The branchly MCP (Model Context Protocol) server exposes your branchly application to AI coding assistants and agents (e.g. OpenCode, Claude Code). Once connected, an AI agent can read and write your knowledge base, manage prompts and AI Actions, and inspect session data — all programmatically.

Setup

The MCP server is scoped to a single application via an API key. Create an API key in the application settings, then add the server to your AI coding tool.

OpenCode — add to your opencode.jsonc:

{
  "mcp": {
    "branchly": {
      "type": "remote",
      "url": "https://api.branchly.io/mcp",
      "enabled": true,
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Claude Code — run once in your terminal:

claude mcp add branchly-app --transport http https://api.branchly.io/mcp -H "x-api-key: YOUR_API_KEY"

Methods

Application

get_application

Returns the full configuration of the connected application: name, embed locations, search settings (mode, models, reranking), chat strategy, locales, and deletion policy.

Use when: you need to inspect or document the current application state.

Knowledge Base — Nodes

Nodes are the atomic units of the knowledge base. Each node has a locale-keyed title and text (HTML), an optional source URL, and optional custom_metadata.

list_nodes

Returns a paginated list of nodes. Supports filtering by:

labels — node type (entry, content, contact, tool)
data_source_types — e.g. website_crawler, file_upload, node_editor, webhook
data_source_ids — one or more specific data source UUIDs
sort_parameters — sort by updated_at ascending or descending

create_node

Creates a new content node. Requires title and text as locale-keyed maps (e.g. {"en": "...", "de": "..."}). Optionally accepts label, source, score_boost and custom_metadata. label defaults to node_editor.

Use when: adding manual FAQ entries, fallback answers, or contact information that isn't covered by a crawled data source.

read_node

Returns the full detail of a single node by ID, including its text content, metadata, score_boost, and data source association.

update_node

Partially updates a node. Supported fields:

title / text — locale-keyed maps; provided locales are merged, others preserved
score_boost — numeric multiplier applied during retrieval ranking (e.g. 1.5 to surface this node more often)
source — canonical URL
custom_metadata — arbitrary key-value metadata; keys are merged

Use when: fixing stale content, enriching node text with user-phrasing variants, or boosting signal for high-value nodes.

Data Sources

Data sources define how content is ingested into the knowledge base (crawling, file upload, API, webhook, etc.).

list_data_sources

Returns all data sources for the application. Supports filtering by data_source_types. Results are ordered by last update.

Supported types:

Type	Description
`website_crawler`	Crawls public websites via Apify
`custom_website_crawler`	Crawl with custom HTML markers and graph builder
`file_upload`	Uploaded PDFs or documents
`openAPI`	API endpoint synced via OpenAPI spec
`helpspace`	Connected helpspace/help center
`webhook`	Data pushed via webhook with custom mapping
`node_editor`	Manually created/edited nodes

update_data_source

Updates a data source. Supports partial updates for name, schedule (cron expression or null to disable), and settings.

tip

settings requires the full object — the API does not merge partial settings. Always read the current data source first, then write back the complete settings with your change applied.

Use when: adjusting crawler selectors (remove_html_elements), changing crawl depth/page limits, or enabling scheduled re-syncs.

Prompts

branchly has three distinct prompt types, each controlling a different interface:

Type	Subtype	Scope
`chat` — `routing_instructions`	Prompt Persona	Decides which AI Actions to call in Chat; drives auto-evaluation. No effect on response tone.
`chat` — `output_instructions`	Output Instructions	Generates the final user-facing Chat response. No effect on routing.
`search_answering`	(none)	Controls the answer generated in the Search interface. No routing/output split.

list_prompts

Returns prompts filtered by prompt_type (chat, search_answering, suggested_questions, chat_evaluation), subtype, and is_active. Returns all when filters are omitted.

create_prompt

Creates a new prompt version and automatically deactivates the previously active prompt of the same type + subtype. There is no separate activation step.

Use when: updating the routing logic, changing response tone/format, or updating the Search answering prompt.

update_prompt

Activates or deactivates an existing prompt by ID. Use is_active=true to restore a previous prompt version (the currently active one is deactivated automatically).

Use when: rolling back to a previous prompt version.

AI Actions (Tools)

AI Actions are callable functions the chat agent can invoke during a conversation (e.g. search the knowledge base, send a contact form, query an external API).

tip

Naming note: The branchly dashboard labels these "AI Actions". The MCP API exposes them via the *_tools methods. Both refer to the same entities.

list_tools

Returns all AI Actions. Pass active=true to return only enabled actions.

read_tool

Returns the full configuration of a single AI Action by ID, including its description, function_arguments, and tool_config.

update_tool

Partially updates an AI Action. Supported fields:

name — snake_case function name (max 64 chars)
description — natural-language description used by the routing agent to decide when to call this action; must be precise and MECE across all actions
active — enable or disable the action
function_arguments — runtime config (e.g. document_limit_default, retrieval_method, data_source_ids_filter for KB tools; recipient email for send-email tools)
tool_config — parameter schema exposed to the LLM (for form and API tools)

Use when: fixing misfiring actions, tuning knowledge base retrieval settings, or disabling unused actions.

Sessions

read_sessions

Returns paginated session summaries ordered by start time descending. Supports filtering by:

interactions — chat, search, navigation, form_submission, voice
embed_types — chat, search, chat_widget, search_interface, voice, api
answer_types — complete, no_knowledge, outside_scope, small_talk, follow_up_question
tool_ids — sessions that involved a specific AI Action
search_query — full-text search across session content

Use when: triaging chatbot failures, identifying no_knowledge or outside_scope patterns, or auditing tool usage.

read_session_detail

Returns the complete interaction history for a single session, including all chat turns, tool calls, documents retrieved, and answer classifications.

Use when: diagnosing a specific failure — checking whether a tool fired, what documents were returned, and how the model reasoned.

Common Workflows

Goal	Methods
Debug a `no_knowledge` response	`read_sessions` → `read_session_detail`
Fix noisy crawled content	`list_data_sources` → `update_data_source` (with full settings)
Boost a high-value node	`read_node` → `update_node` (score_boost)
Add a missing FAQ	`create_node`
Fix an AI Action that never fires	`list_tools` → `read_tool` → `update_tool` (description) + `create_prompt` (routing)
Update the Search answering prompt	`list_prompts(prompt_type="search_answering")` → `create_prompt`
Roll back a prompt	`list_prompts` → `update_prompt` (is_active=true)
Update crawler HTML filters	`list_data_sources` → copy full settings → `update_data_source`

Skills

Also install the official branchly skills https://github.com/branchly-io/branchly-skills for even more detailed instructions on how to use the MCP server.

Setup​

Methods​

Application​

Knowledge Base — Nodes​

Data Sources​

Prompts​

AI Actions (Tools)​

Sessions​

Common Workflows​

Skills​