MCP Tools Reference

The Piper MCP server exposes 40 tools that let you manage agents, files, scenarios, triggers, domains, secrets, MCP servers, and more — all from an MCP-compatible client like Claude Desktop. For setup instructions, see Claude Desktop Integration.

Organization context

Every tool (except list_organizations) requires an org_id parameter — the UUID of the organization to operate on. Use list_organizations to discover your available organizations and their IDs. When using Claude Desktop or Claude Code, Claude will include org_id automatically once it knows which organization you’re working with. You can tell Claude which org to use, or it will call list_organizations to find out.

Agents

list_agents

List agents in the organization. Returns id, name, status, and model info.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“List all my agents”
“Show me which agents are active”
“What models are my agents using?”

get_agent_config

Get full configuration for an agent including linked knowledge, bookmarked documents, tools, and delegates.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`agent_id`	string	Yes	UUID of the agent to inspect

Example prompts

“Show me the full config for my Support Agent”
“What knowledge collections are linked to agent X?”
“Which documents are bookmarked for my agent?”

create_agent

Create a new agent in the organization.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`name`	string	Yes	Agent name (max 255 chars)
`model_provider`	string	Yes	LLM provider (use `list_supported_models` to see valid providers, e.g. “groq”, “openai”, “anthropic”)
`model_name`	string	Yes	Model identifier (use `list_supported_models` with a provider to see IDs)
`internal_name`	string	No	Internal identifier (max 255 chars)
`primary_task_description`	string	No	Primary task description (max 15000 chars)
`business_information_override`	string	No	Override org-level business info (max 10000 chars)
`languages`	array	No	Language codes (default `["en-US"]`)
`is_active`	boolean	No	Whether agent is active (default true)

Example prompts

“Create a new agent called ‘Sales Bot’”
“Set up a Spanish-language support agent”
“Create an inactive agent named ‘Draft Agent’ for testing”

update_agent

Update an existing agent’s configuration.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`agent_id`	string	Yes	UUID of the agent to update
`name`	string	No	New name (max 255 chars)
`internal_name`	string	No	New internal identifier
`primary_task_description`	string	No	New primary task description
`business_information_override`	string	No	Override org-level business info
`model_provider`	string	No	LLM provider (e.g. “groq”, “openai”)
`model_name`	string	No	Model name
`temperature`	number	No	Model temperature (0.0–2.0)
`languages`	array	No	Language codes
`is_active`	boolean	No	Whether agent is active

Example prompts

“Rename my Support Agent to ‘Help Desk’”
“Change the model for agent X to GPT-4”
“Disable agent X”

list_supported_models

List LLM models available to this organization based on configured providers. Use this to discover valid model_provider and model_name values for create_agent and update_agent.Without a provider filter, returns all providers with their default model. With a provider filter, returns all models for that provider.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`provider`	string	No	Provider to filter by (e.g. “groq”, “openai”). If omitted, returns all providers.

Example prompts

“What LLM providers are supported?”
“Show me all models available for Groq”
“What model is my agent using and what are the alternatives?”

Sessions

search_sessions

Search sessions in the organization. Filter by agent and test status.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`agent_id`	string	No	Agent UUID to filter by
`is_test`	boolean	No	Filter for test sessions only
`limit`	integer	No	Max results (default 20, max 100)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“Show me recent sessions for my Support Agent”
“List the last 10 test sessions”
“How many conversations has agent X had?”

get_session_transcript

Get the full event transcript for a session or specific run, including all messages, tool calls, and metrics.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`session_id`	string	Yes	UUID of the session
`run_id`	string	No	UUID of a specific run within the session
`max_runs`	integer	No	Max number of runs to return (default 10, max 50)

Example prompts

“Show me the transcript for session X”
“What tool calls did the agent make in that conversation?”
“How many tokens did the last run use?”

Files

Manage knowledge collections, documents, and bookmarks. Documents are organized in collections, chunked and embedded for semantic search. Agents search files automatically via the search_knowledge tool.

search_knowledge

Search published knowledge documents using semantic similarity (vector search).Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`query`	string	Yes	Natural language search query
`agent_id`	string	No	Agent UUID to scope search to that agent’s collections
`collection_id`	string	No	Collection UUID to search within
`limit`	integer	No	Max results (default 5, max 20)

Example prompts

“Search my files for return policy information”
“What documents mention pricing?”
“Find knowledge related to onboarding in the Support Agent’s collections”

list_collections

List knowledge collections in the organization.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“What collections do I have?”
“List all my collections”

create_collection

Create a new knowledge collection.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`name`	string	Yes	Collection name
`description`	string	No	Collection description

Example prompts

“Create a collection called ‘Product Docs’”
“Add a new collection for FAQ documents”

delete_collection

Delete a knowledge collection and all its documents.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`collection_id`	string	Yes	UUID of the collection to delete

Example prompts

“Delete the old FAQ collection”
“Remove collection X”

list_documents

List documents in a knowledge collection. Returns document metadata including processing status and bookmark mode.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`collection_id`	string	Yes	UUID of the collection
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“Show me the documents in collection X”
“What files are in my FAQ collection?”
“List documents with their processing status”

create_document

Create a text document in a knowledge collection. The document will be automatically chunked and embedded.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`collection_id`	string	Yes	UUID of the collection
`title`	string	Yes	Document title
`content`	string	Yes	Text content (max 1MB)
`language`	string	No	Language code (e.g. “en-US”)

Example prompts

“Add a new document about our return policy to the FAQ collection”
“Create a knowledge document with this content: …”
“Upload this text as a Spanish-language document”

update_document

Update a knowledge document. When content is changed, the document is automatically re-processed (re-chunked and re-embedded).Uses JSON Merge Patch format — only include fields you want to change.Supported fields: title, language, contentParameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`document_id`	string	Yes	UUID of the document to modify
`patch`	object	Yes	JSON Merge Patch with the changes

Example prompts

“Update the title of document X to ‘Returns FAQ’”
“Replace the content of that document with this new version”
“Change the language of document X to Spanish”

delete_document

Delete a document from a collection.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`document_id`	string	Yes	UUID of the document to delete

Example prompts

“Delete document X”
“Remove the outdated policy document”

set_collection_agents

Restrict a collection to specific agents. Only the specified agents will be able to search documents in this collection.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`collection_id`	string	Yes	UUID of the collection
`agent_ids`	array	Yes	List of agent UUIDs that can access this collection

Example prompts

“Restrict the HR collection to only the HR Agent”
“Give agents X and Y access to collection Z”

reset_collection_agents

Reset a collection’s agent access so all agents can search it.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`collection_id`	string	Yes	UUID of the collection

Example prompts

“Make collection X available to all agents”
“Reset agent restrictions on the FAQ collection”

get_document_bookmark

Get the bookmark status for a document, including which agents it’s bookmarked for and the usage description.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`document_id`	string	Yes	UUID of the document

Example prompts

“Is document X bookmarked?”
“Which agents is the return policy bookmarked for?”

set_document_bookmark

Set the bookmark mode for a document. Bookmarked documents appear in the agent’s system prompt with their title and usage description.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`document_id`	string	Yes	UUID of the document
`bookmark_mode`	string	Yes	One of: “off”, “all_agents”, “specific_agents”
`agent_ids`	array	No	Agent UUIDs (required when bookmark_mode is “specific_agents”)
`usage_description`	string	No	Description of when/how the agent should use this document

Example prompts

“Bookmark the return policy for all agents”
“Bookmark the escalation guide for the Support Agent only”
“Remove the bookmark from document X”

Runtime

agent_chat

Send a message to an agent and get a response. The session is tagged as a test run.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`agent_id`	string	Yes	UUID of the agent to invoke
`message`	string	Yes	The user message to send
`session_id`	string	No	Existing session UUID to continue a conversation

Example prompts

“Send ‘What are your hours?’ to my Support Agent”
“Test my agent with a billing question”
“Continue the test conversation in session X with a follow-up”

Scenarios

list_scenarios

List evaluation scenarios in the organization. Supports tag filtering.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)
`tags`	array	No	Filter by tags (returns scenarios matching any tag)

Example prompts

“List all my test scenarios”
“Show scenarios tagged ‘regression’”
“How many scenarios do I have?”

create_scenario

Create a multi-turn evaluation scenario for testing an agent.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`name`	string	Yes	Scenario name (max 255 chars)
`turns`	array	Yes	List of turn objects (see Turn format below)
`description`	string	No	Description of the scenario
`tags`	array	No	List of tags for filtering
`customer_context`	object	No	Context dict for template rendering (e.g. customer info)

Turn formatEach turn object has:

user_message (string, required) — the user’s message. Supports Jinja2 templates: {{ customer.name }}
required (boolean, default true) — if true and the turn fails, subsequent turns are skipped
criteria (array, optional) — evaluation criteria, each with:
- criteria_type — one of llm_evaluated (default), tool_usage, retrieval, retrieval_results, citation
- question — meaning depends on type: for llm_evaluated a yes/no question for the judge (e.g. “Did the agent offer a refund?”); for tool_usage the exact tool name (e.g. “search_knowledge”); for retrieval space-separated search terms; for retrieval_results expected doc name/keywords; for citation expected source doc name or empty string for any citation
- order_index (integer, default 0)
- few_shot_examples (array, optional, llm_evaluated only) — each with response, verdict (“PASS”/“FAIL”), critique

Example prompts

“Create a test scenario that asks about returns then follows up about refund timing”
“Build an evaluation scenario with 3 turns testing billing questions”
“Create a scenario tagged ‘regression’ that tests the greeting flow”

update_scenario

Update an existing evaluation scenario. Only include the fields you want to change.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`scenario_id`	string	Yes	UUID of the scenario to update
`name`	string	No	New scenario name (max 255 chars)
`description`	string	No	New description
`tags`	array	No	New list of tags (replaces existing)
`customer_context`	object	No	New context dict for template rendering
`turns`	array	No	New list of turn objects (replaces existing turns). See `create_scenario` for turn format

Example prompts

“Rename scenario X to ‘Billing Regression’”
“Add a tag ‘critical’ to scenario X”
“Replace the turns in scenario X with these new ones”

run_scenario

Run a scenario against an agent and return detailed results. Executes each turn in sequence, evaluating criteria after each turn. If a required turn fails, subsequent turns are skipped.This is a synchronous call that blocks until the full scenario execution completes (all turns + evaluations). May take 30s+ for multi-turn scenarios with many criteria.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`scenario_id`	string	Yes	UUID of the scenario to run
`agent_id`	string	Yes	UUID of the agent to test

Example prompts

“Run the billing regression scenario against my Support Agent”
“Test agent X with scenario Y and show me the results”
“Execute all my regression scenarios against the new agent”

Triggers

list_triggers

List triggers in the organization.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“List all my triggers”
“Show me my triggers”
“What triggers are configured?”

get_trigger

Get details of a trigger including its configuration.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`trigger_id`	string	Yes	UUID of the trigger

Example prompts

“Show me the config for trigger X”
“What agent is trigger X connected to?”

create_trigger

Create a trigger for an agent. Every trigger gets a webhook URL. Optionally add a cron schedule to also run on a timer.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`name`	string	Yes	Trigger name (1–255 chars)
`agent_id`	string	No	UUID of the agent to invoke (must be active in this org)
`message`	string	No	Message to send to the agent when triggered
`cron_expression`	string	No	Cron expression (5 fields). If provided, the trigger also runs on a schedule
`timezone`	string	No	IANA timezone for scheduled evaluation (default UTC)

Example prompts

“Create a trigger that runs my agent every hour”
“Set up a webhook trigger for agent X”
“Create a daily trigger at 9am EST for the Support Agent”

update_trigger

Update an existing trigger’s configuration.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`trigger_id`	string	Yes	UUID of the trigger to update
`name`	string	No	New name (1–255 chars)
`status`	string	No	New status: “active” or “inactive”
`agent_id`	string	No	New agent UUID
`message`	string	No	New message
`cron_expression`	string	No	New cron expression (5 fields)
`timezone`	string	No	New IANA timezone

Example prompts

“Disable trigger X”
“Change the schedule for trigger X to every 30 minutes”
“Update trigger X to point to a different agent”

list_trigger_runs

List execution history (runs) for a trigger.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`trigger_id`	string	Yes	UUID of the trigger
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“Show me the run history for trigger X”
“Did trigger X run successfully?”
“List recent trigger executions”

Domains

list_allowed_domains

List the organization’s allowed domains for external fetches by agents. Returns header and query parameter templates with {{SECRET_NAME}} placeholders intact (values are never resolved in responses).Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 100, max 500)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“What domains are on the allowlist?”
“Show me the allowed domains for this org”
“Are there any external domains configured?”

create_domain

Add a domain to the organization’s allowlist for external fetches by agents. Headers and query parameters are automatically injected into all HTTP requests to this domain at runtime.Use {{SECRET_NAME}} placeholders to reference encrypted secrets (created via create_secret) — they are resolved at runtime so plaintext values are never stored in domain config.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`domain`	string	Yes	Domain name (e.g. “api.example.com”)
`headers`	object	No	HTTP headers to auto-inject. Use `{{SECRET_NAME}}` to reference secrets (e.g. `{"Authorization": "Bearer {{API_KEY}}"}`)
`query_params`	object	No	Query parameters to auto-inject. Use `{{SECRET_NAME}}` to reference secrets (e.g. `{"api_key": "{{WEATHER_API_KEY}}"}`)

Example prompts

“Add api.example.com to the domain allowlist”
“Allow requests to crm.internal.com with an API key header”

update_domain

Update an allowed domain’s headers or query parameters.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`domain_id`	string	Yes	UUID of the domain to update
`headers`	object	No	New HTTP headers dict (replaces existing). Use `{{SECRET_NAME}}` to reference secrets
`query_params`	object	No	New query parameters dict (replaces existing). Use `{{SECRET_NAME}}` to reference secrets

Example prompts

“Update the API key header for domain X”
“Add query params to the CRM domain”

delete_domain

Delete a domain from the organization’s allowlist. Agents will no longer be able to fetch from this domain.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`domain_id`	string	Yes	UUID of the domain to delete

Example prompts

“Remove api.example.com from the allowlist”
“Delete domain X”

Secrets

list_secrets

List secrets for the organization (metadata only, values never exposed). Secrets can be referenced in allowed domain headers and query parameters using the {{SECRET_NAME}} template syntax.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 100, max 500)
`offset`	integer	No	Pagination offset (default 0)

Example prompts

“List my secrets”
“Show the secrets configured for this org”
“What secret keys are available?”

create_secret

Create an encrypted secret for the organization. Once created, reference this secret in allowed domain headers or query parameters using {{KEY}} syntax (e.g. create a secret with key API_KEY, then set a domain header to {"Authorization": "Bearer {{API_KEY}}"}). The secret value is resolved at runtime and never stored in plaintext in domain config.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`key`	string	Yes	Secret key in `ALL_CAPS_UNDERSCORES` format (for example `OPENAI_API_KEY`)
`value`	string	Yes	Plaintext secret value to store

Example prompts

“Create a secret named OPENAI_API_KEY”
“Store this Slack bot token as SLACK_BOT_TOKEN”
“Add a secret for my webhook signing key”

MCP Servers

list_mcp_servers

List MCP servers configured for the organization.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`limit`	integer	No	Max results (default 50, max 200)
`offset`	integer	No	Pagination offset (default 0)
`include_inactive`	boolean	No	Include deactivated servers (default false)

Example prompts

“What MCP servers are configured?”
“List all active MCP server connections”

get_mcp_server

Get details of an MCP server including its configuration.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`server_id`	string	Yes	UUID of the MCP server

Example prompts

“Show me the config for MCP server X”
“What URL is MCP server X pointing to?”

create_mcp_server

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`name`	string	Yes	Server name
`url`	string	Yes	Server URL endpoint
`description`	string	No	Description
`auth_type`	string	No	Auth type: “bearer” or “header”
`auth_header_name`	string	No	Custom header name (when auth_type is “header”)
`auth_token`	string	No	Auth token (stored encrypted)
`tool_prefix`	string	No	Prefix for tool names from this server
`timeout_seconds`	integer	No	Connection timeout (default 30)
`is_active`	boolean	No	Whether server is active (default true)

Example prompts

“Register a new MCP server at https://tools.example.com/mcp”
“Add an MCP server with bearer token authentication”

update_mcp_server

Update an existing MCP server’s configuration.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`server_id`	string	Yes	UUID of the server to update
`name`	string	No	New server name
`url`	string	No	New server URL
`description`	string	No	New description
`auth_type`	string	No	New auth type
`auth_header_name`	string	No	New header name
`auth_token`	string	No	New auth token
`tool_prefix`	string	No	New tool prefix
`timeout_seconds`	integer	No	New timeout
`is_active`	boolean	No	Whether server is active
`clear_auth`	boolean	No	Set to true to disable authentication (clears auth_type and auth_header_name)

Example prompts

“Update the URL for MCP server X”
“Change the auth token for server X”
“Disable MCP server X”
“Remove authentication from MCP server X”

test_mcp_server

Test connectivity to an MCP server and discover its available tools.Parameters

Name	Type	Required	Description
`org_id`	string	Yes	Organization UUID
`server_id`	string	Yes	UUID of the MCP server to test

Example prompts

“Test the connection to MCP server X”
“What tools does MCP server X provide?”
“Check if server X is reachable”

Organization

list_organizations

List organizations accessible via the current token. Returns the organization id and name.Every other tool requires an org_id parameter. Use this tool first to discover your organization ID, then pass it to subsequent tool calls.ParametersNone.Example prompts

“Which organizations can I access?”
“List my orgs”
“What’s my organization ID?”

Permissions

Each tool requires a specific permission based on your role in the organization. If a tool call returns a permission error, ask your organization admin to update your role.

Tool	Required Permission
`list_agents`, `get_agent_config`, `list_supported_models`	Agents: Read
`create_agent`	Agents: Create
`update_agent`	Agents: Update
`search_sessions`, `get_session_transcript`	Agents: Read
`search_knowledge`, `list_collections`, `list_documents`	Knowledge: Read
`create_collection`, `create_document`	Knowledge: Create
`update_document`, `set_collection_agents`, `reset_collection_agents`	Knowledge: Update
`delete_collection`, `delete_document`	Knowledge: Delete
`get_document_bookmark`, `set_document_bookmark`	Knowledge: Update
`agent_chat`	Runtime: Invoke
`list_scenarios`	Scenarios: Read
`create_scenario`, `update_scenario`	Scenarios: Create / Update
`run_scenario`	Scenarios: Execute
`list_triggers`, `get_trigger`, `list_trigger_runs`	Triggers: Read
`create_trigger`	Triggers: Create
`update_trigger`	Triggers: Update
`list_allowed_domains`	Organization: Read
`create_domain`, `update_domain`, `delete_domain`	Organization: Update
`list_secrets`	Organization: Read
`create_secret`	Organization: Update
`list_mcp_servers`, `get_mcp_server`, `test_mcp_server`	MCP Servers: Read
`create_mcp_server`	MCP Servers: Create
`update_mcp_server`	MCP Servers: Update
`list_organizations`	(any valid token)

Getting Started

Deployment

Integrations

MCP Tools Reference

Organization context

Agents

Sessions

Files

Runtime

Scenarios

Triggers

Domains

Secrets

MCP Servers

Organization

Permissions

Getting Started

Deployment

Integrations

​Organization context

​Agents

​Sessions

​Files

​Runtime

​Scenarios

​Triggers

​Domains

​Secrets

​MCP Servers

​Organization

​Permissions

Organization context

Agents

Sessions

Files

Runtime

Scenarios

Triggers

Domains

Secrets

MCP Servers

Organization

Permissions