Set up an external agent as a BasicOps Agent User

This article shows how to connect an external agent to BasicOps so it becomes an Agent User in BasicOps.

If your agent is hosted on OpenClaw, see Set up an Openclaw Agent User.

This article contains:

1. Adding the agent in BasicOps
2. Connect the external agent to BasicOps’ MCP server
3. Update the external agent’s system prompt
4. Set up a webhook for your external agent
5. Test your BasicOps agent

Requirements:

• You must be a BasicOps administrator in order to be able to add an agent in BasicOps.
• The system hosting the external agent must support connections to MCP servers. The external agent will be using BasicOps’ MCP server to access and modify data in BasicOps.
• It must be possible to activate the external agent via a webhook, and the webhook must be publicly accessible. BasicOps will deliver a webhook payload to the agent’s webhook to trigger the agent when certain things happen in BasicOps, such as a message is sent to the agent or the agent is assigned to a task.

Adding the agent in BasicOps

When you add an agent in BasicOps you’ll get the option to add an API key for the agent. Whether you will need that depends on how you set up MCP connections in the system hosting your external agent - if this supports using OAuth you will not need to add an API key.

Add agent when authorizing with OAuth

Follow these steps to integrate a new agent and generate its corresponding API credential within BasicOps:

1. Navigate to the sidebar and open the Settings menu.
2. Go to the Users section and switch to the Agents view.
3. Select the Add Agent option, provide a designated name, and confirm the creation.
4. When the Add API Key window appears, click the Cancel button - you will not need an API key.

Add agent when authorizing with an API key

Follow these steps to integrate a new agent and generate its corresponding API credential within BasicOps:

1. Navigate to the sidebar and open the Settings menu.
2. Go to the Users section and switch to the Agents view.
3. Select the Add Agent option, provide a designated name, and confirm the creation.
4. When the Add API Key window appears, assign a label to the key—such as the name of your agent—and click Add API Key.
5. Capture the resulting API key from the confirmation screen. Ensure this key is saved securely, as it is required for the subsequent configuration.

Connect the external agent to BasicOps’ MCP server

The way you connect your external agent to BasicOps’ MCP server depends on whether the system hosting your agent supports OAuth or API keys for authorization. In both cases you’ll need the URL for BasicOps’ MCP server:

https://app.basicops.com/mcp?agent=[agent-name]

Replace [agent-name] with the actual name of your agent, but with no spaces. The part ‘?agent=[agent-name]’ is not strictly required, but if you add this, you’ll be able to connect multiple external agents to individual BasicOps agents, each with their own identity.

Set up MCP server using OAuth

If the system hosting your external agent supports OAuth you’ll connect your agent this way:

1. Click the button or link to add an MCP connection - this is typically a Connect button
2. You’ll then be prompted for the MCP URL - enter https://app.basicops.com/mcp?agent=[agent-name] with the actual agent name
3. You’ll then be redirected to BasicOps’ login page, sign in with your credentials
4. When you get to the Grant Permission view select the agent in the ‘Authorize’ drop-down and click the Allow button

The MCP server is then set up and ready to use.

Set up MCP server using an API key

If the system hosting your external agent supports API keys you’ll connect your agent this way:

1. Click the button or link to add an MCP connection - this is typically a Connect button
2. You’ll then be prompted for the MCP URL - enter https://app.basicops.com/mcp?agent=[agent-name] with the actual agent name
3. Enter the agent’s API key (see Add the agent in BasicOps) and click the Add or Submit button

The MCP server is then set up and ready to use.

Testing the BasicOps MCP server

Once you’ve set up the BasicOps MCP server you can test it in your external agent’s chat using the following prompt:

Please call get_current_user in BasicOps

The external agent will then call the BasicOps MCP server and present the result to you. You will see information about the BasicOps agent, including its name and timezone.

Update the external agent’s system prompt

The agent will be activated via a webhook payload sent from BasicOps. The agent needs to know how to interpret the webhook payload and how to respond in BasicOps. To support this, update the external agent’s system prompt (typically stored in a file named AGENT.md) with the instructions shown in System prompt for external agent.

Set up a webhook for your external agent

Locate or add the webhook URL for your external agent. Please note that this URL must be publicly accessible - it will be called by BasicOps to trigger your external agent.

You’ll now ask your external agent to set up the webhook using the BasicOps MCP server. In the external agent’s chat enter the following prompt:

Call connect_agent with webhook set to [PASTE YOUR WEBHOOK HERE],
set kind to [SYSTEM TYPE]

Replace [PASTE YOUR WEBHOOK HERE] with the actual webhook URL, and replace [SYSTEM TYPE] with a short name for the type of system you’re using, such as ‘openclaw’, ‘gumloop’, ‘guild’ or ‘claude’.

If the webhook requires payload signing you can add that to the prompt. You can either provide a secret for the signature, or you ask BasicOps to provide a secret:

If you’re providing the secret, add this to the prompt:

Set signing to “provided” and secret to [YOUR SECRET]

If you want BasicOps to create a secret, add this to the prompt:

Set signing to “generate”, then show the generated secret

If the webhook requires any headers in the payload you can add that to the agent’s prompt like this (the example shows setting up two headers):

set headers to: {"Header-Name-1":”header-value-1",”Header-Name-2":"header-value-2"}

Test your BasicOps agent

Your agent is now ready. In BasicOps, @-mention the agent in any message to ask it something. To use the agent in a project, add it to the project team first. In a direct chat with the agent, @-mentioning is not required. As a first test try this: open a direct chat with the agent in BasicOps and ask it “Are you there”. You should immediately see a ‘Working’ indicator show up under your message, and after a little while, your agent should reply.

For more information about how to use your agent, see Agent Users: Put Your AI Agents to Work With Your Team.