Agents capabilities

Profound MCP gives AI assistants tools to build, manage, and run Profound Agents directly from an MCP client. Use them to create automated workflows that combine Profound data with LLM reasoning, code execution, and web search. To set up the server, see Connecting to Profound MCP. To see what analytics tools are available, see Analytics capabilities.

https://mcp.tryprofound.com/mcp

Profound MCP uses OAuth 2.1. Each tool runs as the authenticated Profound user and returns only the data that user can access.

How the tools work together

Agent workflows fall into two paths: running an existing Agent, or building and publishing a new one.

Run an Agent

Find an Agent

Use list_agents to browse Agents in the organization, or list_agent_definition_templates for pre-built Agent templates.

Inspect inputs

Use get_agent to read the Agent’s input_schema before calling run_agent.

Start a run

Use run_agent with inputs that match the Agent’s input_schema.

Poll for results

Use get_agent_run with the agent_id and the run_id returned in the previous step, until the run reaches a terminal state.

Build an Agent

Open a build session

Use start_agent_build_session with a short, plain-language intent. It returns an agent_build_session_id. Pass that same ID, unchanged, on every build call below so the whole attempt is traced as one session.

Explore building blocks

Use list_agent_node_types and get_agent_node_schema to assemble a workflow graph, or list_agent_definition_templates to start from a template.

Create or update a draft

Use create_agent_definition or update_agent_definition with preview: true to review the plan, then set preview to false to save the draft.

Validate

Use validate_agent_definition to catch structural issues early, and fix them with update_agent_definition. This is a fast pre-check, not the final word: publishing runs the authoritative validation.

Publish

Use publish_agent_definition with preview: true to review the plan, then set preview to false to make the Agent live.

Use natural language when working with Claude

If you’re using Claude as the client, you can prompt it in natural language to build Agents in one go, without calling multiple tools. Here’s an example prompt and an Agent structure Claude may produce with it:

Build an Agent in Profound that creates a structured, AEO-optimized article based on provided inputs. It should analyze top-cited pages, live Google results, and existing brand content to produce a well-researched article

An example diagram outlining the structure of an Agent Claude generated with the prompt above

Behavior and safety

Agents tools can create and update Agent definitions and start Agent runs. Use preview: true (the default) on create, update, and publish tools to review changes before applying them.

Behavior	What it means
Preview before apply	Create, update, and publish tools default to preview mode
Live data	Tools read from the Profound API, so results reflect the caller’s current access and data

Agents tools

These tools let you build, manage, and run Agents directly from an MCP client.

Tool	Use it for
`list_agents`	List Agents available in an organization
`get_agent`	Get details of a specific Agent, including its input schema
`run_agent`	Start an Agent run
`get_agent_run`	Check the status and output of a previously started run
`start_agent_build_session`	Open a build session to build or revise an Agent
`list_agent_node_types`	List the node types available for building an Agent graph
`get_agent_node_schema`	Get the configuration schema for a specific node type
`list_agent_definition_templates`	Browse pre-built Agent templates to use as starting points
`get_agent_definition`	Read back an Agent’s full workflow graph
`create_agent_definition`	Create a new draft Agent definition
`update_agent_definition`	Update an existing draft Agent definition
`validate_agent_definition`	Check whether a draft Agent definition is valid and publishable
`publish_agent_definition`	Publish a draft Agent definition so it goes live

list_agents

List Agents defined in the authenticated organization.

Input	Required	Default	Description
`statuses`	No	`["published"]`	Lifecycle states to include, e.g. `["published"]` or `["draft"]`
`cursor`	No	-	Pagination cursor from a previous page
`limit`	No	-	Maximum number of Agents to return

get_agent

Get details of a specific Agent, including its input_schema. Use this before calling run_agent to confirm which inputs the Agent expects.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the Agent to retrieve
`version`	No	`published`	`published` for the live version, `draft` for the latest unpublished changes

run_agent

Start an Agent run. Returns a run ID you can poll with get_agent_run.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the Agent to run
`inputs`	Yes	-	Input values keyed by the property IDs in the Agent’s `input_schema` (the opaque keys, not the human-readable labels)

Each key in inputs is a property ID from input_schema.properties. The readable label lives in that property’s title. Fetch the schema with get_agent first.Example:

{
  "agent_id": "agent_123",
  "inputs": { "b1f2c3d4-...": "AI search trends" }
}

get_agent_run

Get the status and outputs of a previously started Agent run. Poll this until the run reaches a terminal state.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the Agent the run belongs to
`run_id`	Yes	-	Run ID returned by `run_agent`

start_agent_build_session

Open an Agent build session, the first step before building or revising an Agent. Call it before any other build tool, then pass the returned agent_build_session_id, unchanged, on every subsequent build call so the whole attempt is traced as one session. It persists nothing and does not create an Agent.

Input	Required	Default	Description
`intent`	Yes	-	Short, plain-language description of what the Agent should do

list_agent_node_types

List the node types available for building an Agent graph. Returns each type’s node_type identifier, display name, and a one-line description. Call this after opening a build session, when assembling a new Agent.Inputs: none.

get_agent_node_schema

Get the configuration schema and examples for a specific node type. Use the returned schema to fill a node’s config correctly when building or editing an Agent graph.

Input	Required	Default	Description
`node_type`	Yes	-	Node type identifier from `list_agent_node_types`

Example:

{
  "node_type": "llm"
}

list_agent_definition_templates

Browse pre-built Agent templates. Each template includes a plain-language goal, the inputs it needs, what it produces, and a skeleton workflow you can use as a starting point. Call this before building a new Agent from scratch.Inputs: none.

get_agent_definition

Read back an Agent’s full workflow graph in the same format that create_agent_definition and update_agent_definition accept. Useful for copying an existing Agent or inspecting a node type you want to replicate.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the Agent to read
`version`	No	`published`	`published` for the live version, `draft` for the latest unpublished changes

create_agent_definition

Create a new draft Agent definition. Set preview to true (the default) to see a plain-language plan and workflow diagram without persisting anything. Set preview to false to save the draft after the user confirms.

Input	Required	Default	Description
`name`	Yes	-	Display name for the Agent
`description`	Yes	-	What the Agent does
`organization_id`	Yes	-	Organization to create the Agent in, from `list_organizations`
`graph`	Yes	-	The workflow graph as a `{ nodes, edges }` object
`agent_build_session_id`	Yes	-	Session ID from `start_agent_build_session`
`preview`	No	`true`	Return a plan without saving when `true`; save the draft when `false`

update_agent_definition

Update an existing draft Agent definition. Use this to fix validation issues after create_agent_definition or to iterate on a saved draft. Supports the same preview / apply loop as create_agent_definition.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the draft Agent to update
`graph`	Yes	-	The updated workflow graph
`agent_build_session_id`	Yes	-	Session ID from `start_agent_build_session`
`preview`	No	`true`	Return a plan without saving when `true`; save when `false`

validate_agent_definition

Check whether a saved draft Agent definition is well-formed. Returns valid (boolean), issues (list of actionable errors), and, when the draft is publishable, the input_schema and output_schema the Agent will expose once live. This is a fast structural pre-check: publishing runs the authoritative validation, so a draft can pass here and still be rejected at publish. Fix any issues with update_agent_definition.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the draft Agent to validate
`agent_build_session_id`	Yes	-	Session ID from `start_agent_build_session`

publish_agent_definition

Publish a draft Agent definition so it goes live and is visible across the organization. Supports a preview step that returns a plan before applying. Call validate_agent_definition first to confirm the draft is valid.

Input	Required	Default	Description
`agent_id`	Yes	-	ID of the draft Agent to publish
`agent_build_session_id`	Yes	-	Session ID from `start_agent_build_session`
`preview`	No	`true`	Return a plan without publishing when `true`; publish when `false`

​How the tools work together

​Run an Agent

​Build an Agent

​Use natural language when working with Claude

​Behavior and safety

​Agents tools

How the tools work together

Run an Agent

Build an Agent

Use natural language when working with Claude

Behavior and safety

Agents tools