Custom Integrations (IA and IP)
Custom integrations can be added from the Manage Integrations page in the web app. Use custom integrations to add an MCP server or Custom API.
Model Context Protocol (MCP) Integration
Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems. MCP integrations are used for custom-built tools that do not have a standard integration with Biggy.
MCP integrations can be used with the Observability Agent action plan, or as an ITSM tool.
To create an MCP integration:
On the web app integrations page, click + Add MCP.
Select the Service Type. You can choose from:
Observability: Monitoring, metrics, logs, and traces from observability platforms.
ITSM: IT service management for incident tracking and change workflows.
Context Retrieval: Retrieval-only sources (runbooks, post-mortems, knowledge base content) that Biggy can query for troubleshooting context.
Other: Any other MCP server. Describe what it does, and Biggy will route requests to it based on your description.
Enter a descriptive Name for the MCP.
In the configuration page, populate the following information:
Field
Description
Authentication Method
Select the authentication method that should be used for this MCP server. The following options are available:
Bearer Token: Sent as "Authorization: Bearer <token>". The standard for authenticated MCP servers.
API Key Header: Sent as a request header you name (For example,
X-API-Key: <key>.). For MCPs that expect an API key instead of a bearer token.Basic Auth: Sent as
Authorization: Basicwith a username and password. Rare for MCP servers.OAuth 2.0 (Client Credentials): A short-lived bearer token is obtained from your Token URL using the client credentials grant, then sent in the Authorization header as
Authorization: Bearer <token>.Tokens are refreshed automatically before they expire. With a relay client assigned, the Token URL is reached from inside your network; otherwise, it must be publicly resolvable.
OAuth 2.0 (Authorization Code): An admin authorizes Biggy once at your identity provider. Biggy stores the refresh token and uses it to obtain short-lived bearer tokens, sent as
Authorization: Bearer <token>. Leave the endpoints blank to discover them from the MCP server, and the Client ID blank to register Biggy automatically when the provider supports it.No Authentication: No credentials are sent. This method is typically used only for MCP servers running on your network and accessed via a relay client.
MCP Server URL
Base URL of your MCP server. Include the port if needed.
Authentication
Depending on the selected authentication method, enter your MCP server credentials.
Custom Headers (Optional)
Add custom HTTP headers to include with all API requests. For each header, include the Header Name and Header Value. To add additional headers, click the + sign.
On-Premises Instance
Enable when this MCP instance is only reachable from inside your network. Requests route through a relay client, assigned on the Relay Clients page.
Response Time
Define how long Biggy waits for the server to answer a tool time.
In the Tool call timeout field, select a time in seconds.
Leave blank to use the 60-second default. Raise it only for servers whose queries take longer. The maximum is 5 minutes. Other MCP servers are not affected.
Requester Identity
Enable Share the requesting user's email to allow the server to see which Biggy user is behind the chat request.
How Biggy understands this server
Enter Routing guidance to help Biggy understand when to use this server. Each part pairs the server's self-description with what you write for your environment. When they disagree, your description takes precedence.
Agent Notes
List any notes or guidelines to help Biggy understand your MCP instance. For example, if your logs or alerts contain a specific field used to identify the type of application or service, provide that information here.
We highly recommend configuring this field, as it lets you enter organization-specific information that helps Biggy provide more accurate and consistent results.
Allowed MCP Tools
Choose which tools this MCP server can run on your behalf.
In the Trust Policy section, choose how Biggy decides which tools are callable. Select from the following options:
Allow only selected tools (Recommended): Pick exactly which tools Biggy can call. New tools require explicit approval.
When this option is selected, use the search bar to select one or more tools.
Auto-trust all tools: Allow every tool this server exposes, including tools added in the future.
Human Approval
Decide which tools require explicit human approval before Biggy runs them. The following policies are available:
Destructive only: Default. Only tools that delete or destroy data ask for approval.
All writes: Ask before any tool that writes, modifies, or deletes. Read-only tools still run automatically.
Strict: Gate writes and deletes, plus unclassified tools whose effect can't be determined from their name.
Off: Never ask. Only for fully-trusted servers. Every tool allowed runs without approval.
Click Save Instance.
Custom API
Custom API integrations connect Biggy to your own REST APIs, including in-house tools that don't have a Model Context Protocol (MCP) server.
Change calendars, deployment trackers, service catalogs, and other internal systems often expose a REST API. With Custom APIs, Biggy Chat, workflows, and change risk can call those APIs directly.
Import an existing OpenAPI or Swagger spec, paste a working cURL command, build endpoints by hand, or describe the calls you need and let Biggy draft them for you. Biggy runs read endpoints automatically. Endpoints that change data need an approval. If your API is only reachable inside your network, Biggy can route every call through a relay client.
Key features
Import an OpenAPI 3.x or Swagger 2.0 spec from a URL, a file, or pasted text, and choose which operations Biggy can call.
Build endpoints by hand, from a cURL command, or with Biggy in a chat.
Call saved endpoints from Biggy Chat, workflow steps, and change risk.
Before you start
Identify the base URL of the API you want to connect.
Make sure you have credentials for the sign-in method your API expects.
If you plan to import a spec, have the OpenAPI 3 or Swagger 2.0 spec available as a URL, JSON, or YAML file.
If your API is only reachable inside your network, set up a relay client on the Relay Clients page before you configure the connection.
Create a Custom API integration
In the left navigation, under Integrations, click Manage Integrations.
On the right side of the filter bar, click Add custom integration, then select Custom API.
In the Create Custom API integration modal, enter a Name for the integration.
Below the field, Biggy shows the name it uses for the integration in chat. For example, an integration named "Release Control" appears in chat as
api_release-control.Select a Service type. Options include:
Observability
ITSM
Context Retrieval
Other
Under How do you want to start? select one of the following options:
Import an OpenAPI spec: Every operation in the spec becomes an endpoint Biggy can call. This is the recommended option. See Import an OpenAPI spec.
Build endpoints yourself: Start with no endpoints and add calls one at a time, by hand or from a cURL command. See Build endpoints yourself.
Import an OpenAPI spec
In the Create Custom API integration modal, select Import an OpenAPI spec.
Select how you want to provide the spec:
Spec URL: Enter the URL of the spec, for example
https://<your_api_host>/openapi.json.Upload: Click Choose a JSON or YAML file and select a Swagger 2.0 or OpenAPI 3 file.
Paste: Paste the JSON or YAML of the spec into the text box.
Click Read spec.
Biggy reads the spec before creating anything and shows a summary that includes the API name and version, number of operations, Base URL, Sign-in method, and the counts of reads, writes, and deletes.
(Optional) To limit what Biggy can call, click Choose which.
In the Choose operations modal, select the operations you want to add. Operations are grouped by the tags in the spec.
To select every operation, click All.
To select only read operations, click Reads only.
To clear your selection, click Clear.
To find a specific operation, search by name, path, or tag.
Read operations are selected to start. Operations you don't select stay in the spec, and you can add them later.
To have Biggy test each new read endpoint after import, select Test each new read endpoint after import.
Click Use these operations.
Click Import and create.
Biggy creates the integration and opens its page. A banner shows how many endpoints are on, how many reads are on, how many writes ask for approval, and how many safe reads are waiting for sign-in. To continue, click Add sign-in and configure the connection.
Information saved from the spec
Biggy saves the base URL and sign-in method from the spec, so you only need to add the credentials on the integration page. Once Biggy can sign in, it tests the read endpoints it can call safely. It never sends a write request as a test.
Integration starts disabled
A new integration is off when it is created. Read endpoints are on, and write endpoints ask for approval. Biggy doesn't call any endpoint until you enable the integration.
Build endpoints yourself
In the Create Custom API integration modal, select Build endpoints yourself.
Click Create.
Biggy creates the integration and opens its page. On the integration page, configure the connection, then add your first endpoint. The integration starts disabled until you enable it.
The integration page
Each Custom API integration has its own page. To view or edit an integration, in the Manage Integrations page, select the integration, and click Configure on the integration tile. The tile shows the integration name, an API badge, its service type, and its endpoint count.
The top of the integration page includes:
Header: The integration name, the Beta badge, and the toggle that enables the integration.
Progress steps: Where you are in setup: Endpoints, Add sign-in, Test safe reads, and Enable.
Setup guide: Lists the setup steps in order. Click the arrow to expand or collapse the guide.
Summary card: The name Biggy uses in chat, for example
api_release-control, and the service type.
The rest of the page contains the following sections:
To save changes to the page, click Save Instance at the bottom of the page.
Configure the connection
Use the Connection section to configure the base URL and sign-in method Biggy uses for every call to your API.
In the Connection section, select an Authentication method. The following options are available:
Bearer Token
API Key
Basic Auth
OAuth 2.0 (Client Credentials)
OAuth 2.0 (Authorization Code)
No Authentication
Enter the Base URL of your API. If you imported a spec, Biggy fills in the base URL from the spec.
Enter the credentials for the selected method. See Sign-in methods.
(Optional) Add custom HTTP headers to include with all API requests. For each header, include the Header Name and Header Value. To add additional headers, click the + sign.
If the API is only reachable inside your network, turn on On-premises instance. On-prem integrations can connect via the Relay Client, enabling secure communication with infrastructure behind your firewall.
Click Verify Connection to ensure the credentials are working.
Sign-in stays with the connection
Biggy adds the sign-in to every call itself, after all other inputs. Credentials never sit in an endpoint, and nothing a user types can replace them. Saved secrets stay masked.
Sign-in methods
Custom API supports six sign-in methods. Use the table below to see what fields must be configured depending on the method you choose.
Method | Fields | How Biggy sends it |
|---|---|---|
Bearer Token | Bearer Token |
|
API Key | Send the key as (select Request header or Query parameter) API Key Header Name API Key | As a request header, for example |
Basic Auth | Username Password |
|
OAuth 2.0 (Client Credentials) | Token URL Client ID Client Secret Scope (optional) | Biggy gets a short-lived bearer token from the token URL with the client credentials grant, then sends |
OAuth 2.0 (Authorization Code) | Authorization URL (optional) Token URL (optional) Client ID (optional) Client secret (optional) Scope (optional) Redirect URL | An admin authorizes Biggy once at your identity provider. Biggy stores the refresh token and uses it to get short-lived bearer tokens, sent as |
No Authentication | None | No sign-in is added |
Tell Biggy how to use the API
The How Biggy understands this API section gives Biggy context about the whole integration. Biggy receives what you write here with every endpoint of the integration.
When to use it: Describe what the API holds and what questions it answers.
For example: "Our change calendar, deployment tracker, and service catalog. Use it to answer what changed on a service, who owns it, and whether a change freeze is in effect."
Agent notes: Add field meanings, ID formats, and anything else Biggy should know when it calls your API.
For example: "Change numbers look like CHG0041872. Service IDs are lowercase. All times are UTC."
Improve short descriptions on import: When this toggle is on, Biggy rewrites one-word or missing endpoint descriptions from the spec so it picks the right endpoint. You can edit any of them later. This toggle is on by default.
Write clear descriptions
Biggy decides which endpoint to call based on these descriptions. Describe the data in your API's own terms, and include ID formats and time zones so Biggy can fill inputs correctly.
Add and manage endpoints
An endpoint is one call Biggy can make to your API. The Endpoints section lists every endpoint on the integration.
Add an endpoint
In the Endpoints section, click Add endpoint. The New endpoint page opens.
(Optional) To fill in the form from a working call, paste a cURL command into Start from cURL and click Fill in from cURL. See Start from a cURL command.
In the Request section, configure the call:
Method: Select the HTTP method.
Path: Enter the path that Biggy adds to the base URL, for example
/v1/changes. For any part of the path the agent fills in, use a placeholder such as{changeId}. Biggy shows the full URL below the field and lists the path parameters it detects.Name: Enter the name Biggy sees the endpoint by. Use letters, numbers,
_, or-. Biggy suggests a name based on the method and path.Tag (optional): Enter a tag to group the endpoint. Search on the integration page matches tags.
In the Inputs section, click Add input for each value the request needs. Enter the following inputs:
Name: The parameter name your API expects.
In: Where the value goes in the request. Select from Path, Query, Header, or Body.
Type: The value type. Select from Text, Number, Whole number, True/False, One of a list, Object, or List.
Filled by: Who provides the value. Select from Agent, Fixed, or Context.
Required: Turn on if the request can't be sent without this value.
Description: What the agent reads to understand the input.
In the What Biggy is told section, describe when Biggy should call the endpoint and what it keeps from the response. Configure the following fields:
When to use it: Describe when Biggy should call this endpoint and what it returns. Up to 800 characters.
Summary (optional): A one-line description used in endpoint lists and approval prompts.
Response kept: The part of the response Biggy keeps. Leave blank to keep the whole response. For example,
$.items[*].{id,title}keeps the id and title fields of each item. A path that matches nothing keeps everything.Size cap: The maximum number of characters Biggy keeps from the response. The default is 8,000 characters, up to a maximum of 40,000.
In the Safety section, review the risk level and approval settings. Configure the following fields:
In chat: Select how this endpoint behaves in chat. Select from the following options:
Follow policy: Runs without asking (the All writes policy).
Always ask: Asks for approval every time.
Runs without asking: Runs without asking.
On: Turn off to stop Biggy from calling this endpoint while keeping it saved.
(Optional) On the right side of the page, use the Test tab to test the endpoint before you save.
Click Create endpoint.
Endpoints imported from a spec are grouped by their tags. Endpoints you build on the integration page are listed under Built here.
Start from a cURL command
If you already have a call that works, paste it as a cURL command and Biggy fills in the form.
On the New endpoint page, paste the command into Start from cURL.
Click Fill in from cURL.
Biggy fills in the method, path, and inputs, and lists what it changed and why:
Removed: A header that matches the integration's sign-in, such as an API key header, is dropped. The integration adds its own sign-in to every call, so Biggy doesn't keep the key from your command.
Input: IDs in the URL become path inputs, and query parameters become inputs that the agent fills in.
Review each field before you save the endpoint.
Build endpoints with Biggy
The Build with Biggy panel next to the endpoint form lets you describe the calls you need in natural language. Biggy fills in the form, tests the draft against your API, and can draft several endpoints at once.
Biggy tests reads only
Biggy sends read requests to your API to test them. It shows write requests without sending them.
On the New endpoint page, on the right side of the page, click the Build with Biggy tab.
Paste a cURL command, API docs for an endpoint, or describe the calls you need.
Send your message. Biggy plans, drafts, and tests the endpoints, then summarizes what it built.
Review each draft. When Biggy drafts more than one endpoint, use the draft indicator, for example Draft 1 of 2, and Next to move between them. Each field Biggy filled carries a Drafted badge. When Biggy chose what to keep after seeing a real response, the Response kept field carries a From test badge.
(Optional) To change a draft, ask Biggy in the chat.
Click Save endpoints to save every draft at once, or click Discard drafts.
Import operations from a spec
You can import operations from a spec, including into an integration you started from scratch.
In the Endpoints section, click Import spec.
In the Import a spec modal, select Spec URL, Upload, or Paste, and provide the spec.
Click Read spec, then choose the operations to add.
Endpoints you already have stay as they are unless you replace them.
Update to a new spec version
When your API ships a new version, import the new spec. Before applying changes, Biggy shows the Review the new version modal with:
Added: Operations that are new in this version.
Removed: Operations that are no longer in the spec.
Changed: Operations that changed, for example an added input.
Changes that affect endpoints that are on are marked is on.
Review the changes.
Choose whether to turn on Remove endpoints no longer in the spec. The modal shows how many endpoints would be deleted.
Click Apply new version, or click Back to return without applying.
Removing endpoints
When Remove endpoints no longer in the spec is on, Biggy deletes those endpoints, including those that are on. Workflows and change risk sources that use a deleted endpoint stop at that step until you select a different endpoint.
Find and manage endpoints
The Endpoints section lists each endpoint with its method, name, risk badge, path, description, and latest test result. Each endpoint has its own toggle to turn it on or off.
To filter the list, select All, Reads, Writes, or Failed test.
To search, enter text in Filter endpoints. Search matches names, paths, descriptions, and tags.
To edit an endpoint, click the endpoint row.
Delete an endpoint
Open the endpoint and click Delete.
In the delete confirmation box, review the list of workflows and change risk sources that still use the endpoint.
Click Delete endpoint.
After you delete an endpoint, Biggy can no longer call it. Workflows that use it stop at that step. Items that use it stay saved and show the endpoint as missing until you choose another one.
Test an endpoint
The Test tab on the right side of the endpoint page runs whatever is in the form, saved or not. Agent inputs appear as fields you can fill in. Fixed and context inputs fill themselves in.
On the endpoint page, click the Test tab.
Enter values for any inputs you want to test.
Select a test mode and click :
Show request only: Biggy builds the request exactly as it would send it, checks it, then stops. Nothing reaches your API.
Send for real: Biggy sends the request to your API and shows what comes back.
Check that the content is correct, and either click Check request or Run test.
To run the test against the last saved version of the endpoint instead of the form, click Retest saved version.
Test results include:
Whether Biggy ran. For example, if the path has no unfilled placeholders, the connection's sign-in was added last, the relay client is online, and the request stays on your base URL.
The request Biggy built or sent, with secrets masked.
For Send for real, the HTTP status, the response time, and the response size before and after Biggy applies Response kept. Select What Biggy sees to view the kept response, or Raw to view the full response.
Testing a write
For an endpoint that can change data, the Test tab shows the warning "Testing this endpoint can change data." Before you can send it for real, you must select I understand this will change data in your API.
Human approval
The Human approval section determines which endpoint calls require a person to approve them in chat.
Under Default policy, select one of the following:
Policy | Behavior |
|---|---|
Destructive only |
|
All writes | Anything that changes data requires approval. Reads run automatically. This is the default policy. |
Strict | Every endpoint asks for approval, including reads. You can allow individual endpoints to run without asking. |
Under Per-endpoint approval, use the Require approval toggle to override the default policy for any endpoint that is on. DELETE endpoints always ask for approval and can't be overridden.
Turn on endpoints
Turn on endpoints in the Endpoints section before you fine-tune approval per endpoint.
Who may approve or trigger writes follows the roles in Access Controls.
Enable the integration
A new integration starts disabled. Before you can enable it, you must save all required credentials and turn on at least one endpoint.
Open the integration page.
In the header card, turn on the toggle.
After you enable the integration, Biggy Chat, workflows, and change risk can call its endpoints.
Use the integration in Biggy Chat
When the integration is enabled, ask Biggy Chat a question the API can answer. For example: "What changed on checkout-api, and is a freeze in effect?" Biggy chooses the endpoints to call based on their descriptions.
To see which calls Biggy made, open the run in the chat response. The run lists each call to the integration and Biggy's reasoning.
When an answer needs a call that requires approval, Biggy stops and shows an Approval requested card. The card shows the method, the path, the integration, the endpoint, and the inputs that will be sent. Select one of the following:
Approve: Send the call as shown.
Reject: Don't send the call.
Edit: Change what will be sent before you approve it.
Use endpoints in workflows
A workflow can call an endpoint as a step, with no model involved. Each input comes from a fixed value, the workflow trigger, or an earlier step, and later steps can use the response.
In the workflow editor, add a Call API endpoint step.
In the Configure Call API endpoint Step modal, enter a Step name (optional).
Select the Connection, which is your Custom API integration.
Select the Endpoint. Read endpoints are always available. Write endpoints are available only after you turn on Allow in workflows for the endpoint.
Under Inputs, select a source for each input: Not set, Fixed value, From the trigger, or From an earlier step.
Click Done.
Use endpoints in change risk
Change risk can read a Custom API endpoint for context on every change, for example, to check for an active freeze window. Change risk only calls read endpoints. Endpoints that change data are listed but can't be selected.
In your change risk configuration, add a source and select Custom API endpoint under Query for context.
In Request Configuration, select the Custom API connection and the Endpoint. The endpoint defines the request, its sign-in, and how much of the response Biggy keeps.
Under Inputs, enter a value for each input. To use a value from the change request, enter a parameter reference, for example
{{cmdbCiSysId}}.(Optional) In Parameters, click Add Parameter to define a dynamic value that changes per change request. For example, map a parameter named
cmdbCiSysIdtochange.cmdb_ci.value.(Optional) Configure an Execution Condition.
Troubleshooting
Symptom | Likely cause | Solution |
|---|---|---|
The enable toggle is unavailable. | Required credentials aren't saved, or no endpoint is on. | Add the sign-in, click Save Instance, and turn on at least one endpoint. |
Endpoint calls fail with an OAuth 2.0 (Authorization Code) connection. | Nobody has authorized Biggy at the identity provider. | Save your changes, then click Authorize in the Connection section. |
Verify Connection fails on an on-premises connection. | The relay client is offline or the integration isn't assigned to it. | On the Relay Clients page, confirm the relay client is connected and the integration appears in Assigned Integrations, then click Restart Tunnel. |
Changes in the Connection section are lost. | Verify Connection tests the form but doesn't save it. | Click Save Instance after you verify. |
Run test is unavailable for a write endpoint. | Writes need confirmation before Biggy sends them. | Select I understand this will change data in your API. |
A write endpoint isn't available in a workflow step. | Writes stay out of workflows by default. | On the endpoint, turn on Allow in workflows. |
A | Biggy treats | On the endpoint, turn on Only reads. |
Biggy keeps too much or too little of a response. | Response kept or Size cap doesn't match the response shape. | Run a test with Send for real, compare What Biggy sees with Raw, then adjust Response kept or Size cap. |