# Create Tool

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Tool"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/workspaces/{workspace_id}/tools"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new tool.

This unified endpoint handles creation for all tool types
(MCP server tools and pipeline tools).

For MCP server tools, provide mcp_server data with URL, transport type, and
optional secret ID. For pipeline tools, provide pipeline data with pipeline ID
and optional input/output mappings.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"description":"Type the id of the workspace.","in":"path","name":"workspace_id","required":true,"schema":{"description":"Type the id of the workspace.","format":"uuid","title":"Workspace Id","type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"anyOf":[{"description":"MCP server tool to validate or create.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of what the tool does","title":"Description"},"mcp_server":{"description":"MCP server configuration data","properties":{"mcp_transport":{"description":"Transport protocol for the MCP server (sse or http)","enum":["sse","http"],"title":"MCPTransport","type":"string"},"secret":{"anyOf":[{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name of the secret.","title":"Secret Name"},"secret":{"description":"The secret you want to add.","title":"Secret","type":"string"}},"required":["secret"],"title":"Create Secret","type":"object"},{"type":"string"},{"type":"null"}],"description":"Optional secret to use for authentication. Can be a secret ID, a secret name or a new secret to create.","title":"Secret"},"url":{"description":"URL of the MCP server","title":"Url","type":"string"}},"required":["url","mcp_transport"],"title":"CreateMCPServerToolData","type":"object"},"name":{"description":"The name of the tool","title":"Name","type":"string"},"tool_type":{"const":"mcp","default":"mcp","description":"Type of tool, must be 'mcp'","title":"Tool Type","type":"string"}},"required":["name","mcp_server"],"title":"MCPServerToolRequest","type":"object"},{"description":"Pipeline tool to validate or create.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of what the tool does","title":"Description"},"name":{"description":"The name of the tool","title":"Name","type":"string"},"pipeline":{"description":"Pipeline configuration data","properties":{"inputs_outputs":{"anyOf":[{"description":"Model for Pipeline tool inputs and outputs","properties":{"inputs":{"additionalProperties":{"description":"Model for tool input configuration.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description explaining what this input represents and how it should be used","title":"Description"},"from":{"description":"Source location for the tool input (LLM or STATE)","enum":["LLM","STATE"],"title":"ToolInputFrom","type":"string"}},"required":["from"],"title":"ToolInputConfig","type":"object"},"description":"Mapping of input names to their configuration (source and optional description)","title":"Inputs","type":"object"},"outputs":{"additionalProperties":{"description":"Model for tool output configuration.","properties":{"to":{"description":"Destination location(s) for the tool output (LLM, STATE, or LLM_AND_STATE)","enum":["LLM","STATE","LLM_AND_STATE"],"title":"ToolOutputTo","type":"string"}},"required":["to"],"title":"ToolOutputConfig","type":"object"},"description":"Mapping of output names to their configuration (destination)","title":"Outputs","type":"object"}},"title":"PipelineToolInputsOutputs","type":"object"},{"type":"null"}],"description":"Inputs and outputs configuration for the pipeline tool."},"pipeline_definition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"The definition of the pipeline as a dictionary","title":"Pipeline Definition"},"pipeline_template_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The ID of the pipeline template to use.","title":"Pipeline Template Id"},"pipeline_version_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The ID of the pipeline version to use.","title":"Pipeline Version Id"}},"title":"PipelineToolData","type":"object"},"tool_type":{"const":"pipeline","default":"pipeline","description":"Type of tool, must be 'pipeline'","title":"Tool Type","type":"string"}},"required":["name","pipeline"],"title":"PipelineToolRequest","type":"object"},{"description":"Code tool to validate or create.","properties":{"code":{"description":"Code tool configuration data.","properties":{"code":{"description":"The code snippet to be executed as a tool.","title":"Code","type":"string"}},"required":["code"],"title":"CodeToolData","type":"object"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of what the tool does","title":"Description"},"name":{"description":"The name of the tool","title":"Name","type":"string"},"tool_type":{"const":"code","default":"code","description":"Type of tool, will be 'code'","title":"Tool Type","type":"string"}},"required":["name","code"],"title":"CodeToolRequest","type":"object"},{"description":"Component tool to validate or create.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of what the tool does","title":"Description"},"name":{"description":"The name of the tool","title":"Name","type":"string"},"tool_type":{"const":"component","default":"component","description":"Type of tool, must be 'component'","title":"Tool Type","type":"string"}},"required":["name"],"title":"ComponentToolRequest","type":"object"}],"title":"Request"}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"content":{"application/json":{"schema":{"anyOf":[{"description":"Model for an MCP Server tool response.","properties":{"connected":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the MCP server is currently connected: true when reachable, false when unreachable, and null/omitted when connect_mcp=false.","title":"Connected"},"created_at":{"description":"Timestamp when the tool was created","format":"date-time","title":"Created At","type":"string"},"created_by":{"anyOf":[{"properties":{"family_name":{"description":"Family name of a user.","title":"Family name","type":"string"},"given_name":{"description":"Given name of a user.","title":"Given name","type":"string"},"user_id":{"description":"Unique identifier of a user.","format":"uuid","title":"User ID","type":"string"}},"required":["given_name","family_name","user_id"],"title":"Oauth User","type":"object"},{"type":"null"}],"description":"User who created the tool","title":"Created By"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of what the tool does","title":"Description"},"errors":{"description":"List of validation errors, if any.","items":{"type":"string"},"title":"Errors","type":"array"},"mcp_server":{"description":"MCP server configuration data","properties":{"mcp_transport":{"description":"Transport protocol for the MCP server (sse or http)","enum":["sse","http"],"title":"MCPTransport","type":"string"},"secret":{"anyOf":[{"properties":{"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"The date and time when the secret was created.","title":"Created At"},"created_by":{"anyOf":[{"properties":{"family_name":{"description":"Family name of a user.","title":"Family name","type":"string"},"given_name":{"description":"Given name of a user.","title":"Given name","type":"string"},"user_id":{"description":"Unique identifier of a user.","format":"uuid","title":"User ID","type":"string"}},"required":["given_name","family_name","user_id"],"title":"Oauth User","type":"object"},{"type":"null"}],"description":"The user who created the secret.","title":"Created By"},"last_edited_by":{"anyOf":[{"properties":{"family_name":{"description":"Family name of a user.","title":"Family name","type":"string"},"given_name":{"description":"Given name of a user.","title":"Given name","type":"string"},"user_id":{"description":"Unique identifier of a user.","format":"uuid","title":"User ID","type":"string"}},"required":["given_name","family_name","user_id"],"title":"Oauth User","type":"object"},{"type":"null"}],"description":"The user who last edited the secret.","title":"Last Edited By"},"masked_secret":{"description":"Masked secret value. The actual secret is not returned for security reasons.","title":"Masked Secret","type":"string"},"name":{"description":"The name of the secret.","title":"Secret Name","type":"string"},"secret_id":{"description":"Unique identifier of the secret.","format":"uuid","title":"Secret ID","type":"string"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"The date and time when the secret was last updated.","title":"Updated At"},"workspace":{"anyOf":[{"properties":{"name":{"description":"Name of the workspace.","title":"Workspace Name","type":"string"},"workspace_id":{"description":"Unique identifier of the workspace","format":"uuid","title":"Workspace ID","type":"string"}},"required":["workspace_id","name"],"title":"Workspace","type":"object"},{"type":"null"}],"description":"The workspace the secret belongs to. If not provided, the secret is global to the organization.","title":"Workspace"}},"required":["secret_id","name","masked_secret"],"title":"Get Secret","type":"object"},{"type":"null"}],"description":"Optional secret to use for authentication. Can be a secret ID, a secret name or a new secret to create."},"url":{"description":"URL of the MCP server","title":"Url","type":"string"}},"required":["url","mcp_transport"],"title":"MCPServerToolData","type":"object"},"name":{"description":"The name of the tool","title":"Name","type":"string"},"tool_definition":{"additionalProperties":true,"description":"Definition of the tool, for example to be used in the Agent's tools init parameter.","title":"Tool Definition","type":"object"},"tool_id":{"description":"Unique identifier for the tool","format":"uuid","title":"Tool Id","type":"string"},"tool_type":{"const":"mcp","default":"mcp","description":"Type of tool, will be 'mcp'","title":"Tool Type","type":"string"},"tools":{"anyOf":[{"items":{"description":"Model for an MCP tool.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of the MCP tool","title":"Description"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Input schema of the tool","title":"Input Schema"},"name":{"description":"Name of the MCP tool","title":"Name","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology. If not provided, the name should be used for display.","title":"Title"}},"required":["name"],"title":"MCPTool","type":"object"},"type":"array"},{"type":"null"}],"description":"List of tools available from the MCP server","title":"Tools"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Timestamp when the tool was last updated","title":"Updated At"}},"required":["name","tool_id","created_at","tool_definition","mcp_server","connected"],"title":"MCPServerTool","type":"object"},{"description":"Model for a Pipeline tool response.","properties":{"created_at":{"description":"Timestamp when the tool was created","format":"date-time","title":"Created At","type":"string"},"created_by":{"anyOf":[{"properties":{"family_name":{"description":"Family name of a user.","title":"Family name","type":"string"},"given_name":{"description":"Given name of a user.","title":"Given name","type":"string"},"user_id":{"description":"Unique identifier of a user.","format":"uuid","title":"User ID","type":"string"}},"required":["given_name","family_name","user_id"],"title":"Oauth User","type":"object"},{"type":"null"}],"description":"User who created the tool","title":"Created By"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description of what the tool does","title":"Description"},"name":{"description":"The name of the tool","title":"Name","type":"string"},"pipeline":{"description":"Pipeline configuration data","properties":{"inputs_outputs":{"anyOf":[{"description":"Model for Pipeline tool inputs and outputs","properties":{"inputs":{"additionalProperties":{"description":"Model for tool input configuration.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional description explaining what this input represents and how it should be used","title":"Description"},"from":{"description":"Source location for the tool input (LLM or STATE)","enum":["LLM","STATE"],"title":"ToolInputFrom","type":"string"}},"required":["from"],"title":"ToolInputConfig","type":"object"},"description":"Mapping of input names to their configuration (source and optional description)","title":"Inputs","type":"object"},"outputs":{"additionalProperties":{"description":"Model for tool output configuration.","properties":{"to":{"description":"Destination location(s) for the tool output (LLM, STATE, or LLM_AND_STATE)","enum":["LLM","STATE","LLM_AND_STATE"],"title":"ToolOutputTo","type":"string"}},"required":["to"],"title":"ToolOutputConfig","type":"object"},"description":"Mapping of output names to their configuration (destination)","title":"Outputs","type":"object"}},"title":"PipelineToolInputsOutputs","type":"object"},{"type":"null"}],"description":"Inputs and outputs configuration for the pipeline tool."},"pipeline_definition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"The definition of the pipeline as a dictionary","title":"Pipeline Definition"},"pipeline_template_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The ID of the pipeline template to use.","title":"Pipeline Template Id"},"pipeline_version_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The ID of the pipeline version to use.","title":"Pipeline Version Id"}},"title":"PipelineToolData","type":"object"},"tool_definition":{"additionalProperties":true,"description":"Definition of the tool, for example to be used in the Agent's tools init parameter.","title":"Tool Definition","type":"object"},"tool_id":{"description":"Unique identifier for the tool","format":"uuid","title":"Tool Id","type":"string"},"tool_type":{"const":"pipeline","default":"pipeline","description":"Type of tool, will be 'pipeline'","title":"Tool Type","type":"string"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Timestamp when the tool was last updated","title":"Updated At"}},"required":["name","tool_id","created_at","tool_definition","pipeline"],"title":"PipelineTool","type":"object"}],"title":"Response Create Tool Api V2 Workspaces  Workspace Id  Tools Post"}}},"description":"Successful Response"},"400":{"description":"Raised when MCP server connection failed"},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"},"424":{"description":"Error indicating that the secret used by the tool was not found."}}}
>
  
</StatusCodes>