Skip to main content
To send requests to integrations or APIs that aren’t yet supported by our catalog of tools available in ActionKit, you can use the Proxy API to create a Custom Tool for any use case.

​
Usage

To send a custom request to any API for an integration in your Paragon project, use the following base URL with a Paragon User Token (JWT) as a Bearer token in the Authorization header. Base URL 
https://proxy.useparagon.com/projects/[Project ID]/sdk/proxy/[integration]

https://worker-proxy.[On-Prem Base URL]/projects/[Project ID]/sdk/proxy/[integration]
Then, specify the path or full URL of a custom integration request to send on behalf of your user as the header X-Paragon-Proxy-Url (or directly appended to the base URL). For example, if you are trying to reach the comments.list endpoint of Google Drive, which has the URL: 
GET https://www.googleapis.com/drive/v3/files/{fileId}/comments
…the custom request would be structured as: 
GET https://proxy.useparagon.com/projects/[Project ID]/sdk/proxy/googledrive

Authorization: Bearer [Paragon User Token]
X-Paragon-Proxy-Url: https://www.googleapis.com/drive/v3/files/{fileId}/comments
Proxy API requests can be sent for any of the 130+ integrations available in our catalog or with Custom Integrations, so you can add Custom Tools for any API.
Custom Tool definitions will not appear in the List Tools endpoint, which only includes Paragon-defined Tools.See below for examples of defining Custom Tools within your application or our MCP to drive Proxy API requests.

​
Examples

​
Custom Tool for Tool Calling

A Custom Tool can be defined in your system as one or many Proxy API calls that are made for a given set of input parameters. A basic implementation of a Custom Tool would look like the following: 
// Create JSON Schema of a Get Comments tool:
const getFileCommentsTool = {
  "type": "function",
  "name": "get_file_comments",
  "description": "Get comments for a specific file in Google Drive",
  "parameters": {
    "type": "object",
    "properties": {
      "fileId": {
        "type": "string",
        "description": "The ID of the file to get comments for"
      }
    },
    "required": ["fileId"]
  }
}

// When receiving this tool call, make the proxy request:
if (outputItem.type === "function_call" && outputItem.name === getFileCommentsTool.name) {
  const { fileId } = item.arguments;
  const response = await fetch(
    `https://proxy.useparagon.com/projects/${PROJECT_ID}/sdk/proxy/googledrive`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${getUserToken()}`,
        'X-Paragon-Proxy-Url': `https://www.googleapis.com/drive/v3/files/${fileId}/comments`
      }
    }
  );

  // Make additional requests or transformations...
  let output = await response.text();

  // Return to the model:
  input.push({
    type: "function_call_output",
    call_id: outputItem.call_id,
    output,
  });

  await responses.create(...);
};
The 2 key components to implement:
  1. Define a JSON Schema for your Custom Tool that you will pass to the model as a tool definition (in addition to the native ActionKit definitions).
  2. When your Custom Tool is called, call the Proxy API with the input and return the output to the model (or make additional requests / transformations).

​
OpenAPI as Custom Tools

If you have an OpenAPI spec defining a list of endpoints that you want to add as available tools, you can transform those automatically into Custom Tools as described above that send requests to the Proxy API. Our open-source MCP does this out-of-the-box by accepting OpenAPI specs in the openapi/ folder of your server:

useparagon/paragon-mcp

You can also adapt the implementation yourself for use outside of MCP. The key areas to adapt from are:
  1. Transforming OpenAPI fields to JSON Schemas that can be used as tool definitions. (Source)
  2. Calling the Proxy API with the input (and path parameters resolved in the URL) given a tool call request from an LLM. (Source)