Browse Platform

PlatformProjectConnections

Platform · Project

Connections

Connect a project to applications, MCP servers, BotDojo resources, and the tools that workspaces, agents, and flows can use.

15 min read

A Connection gives users, workspace agents, and flows a controlled set of tools from an application, Model Context Protocol (MCP) server, or BotDojo resource. The Connection is the security boundary: it determines which tools are exposed, who can discover the Connection, and what approval each tool requires.

Use the links below to jump directly to a task:

Create a Connection
Review every Connection setting
Configure tools and approvals
Choose a Connection type
Connect a remote MCP server
Export a Connection as MCP
Understand Connections and Integrations

How a Connection works

Application Integration
Remote MCP server
BotDojo resource
          ↓
Connection
Identity • visibility • tools • approvals
          ↓
Users • workspace agents • flows • MCP clients

A Source supplies the tools. It can be an application Integration, a remote or container-backed MCP server, or a BotDojo resource such as an index.
A Connection is the project-owned security boundary around that source. It has a stable URI, visibility and sharing settings, and a tool policy.
Tools are the actions discovered from the source. A tool can be disabled, renamed for agents, and configured to Deny, Ask, or Allow each call.

Users and agents work through the Connection. They do not receive the provider's credential directly, and access to a flow or workspace does not by itself grant access to the Connection.

Open Connections

In a project, select Connections under Context. The list shows each Connection's name, discovered tool count, sharing scope, and last modification time.

The project Connections page with a Notion connection and eight discovered tools

Select Refresh to reload the list.
Select a Connection name to open its settings.
Select Add Connection to browse available sources.

Create a Connection from the browser

Select Add Connection to open the Connection browser. It combines connected applications, catalog MCP servers, custom MCP servers, and BotDojo resources in one place.

The Add Connection browser with search, integration, Custom MCP, and index filters

To create a Connection:

Search by name or use Integrations, Custom MCP, and Indexes to narrow the browser.
Select the source card you want. Use Add Custom Connection when an external MCP server is not listed.
For an application source, select an existing Integration. If no eligible Integration exists, BotDojo opens the provider setup and creates an Integration before continuing with the Connection.
Review the Connection name, description, URI, sharing, and default visibility.
Save the Connection, then review the tools BotDojo discovered from the source.

The labels on the cards describe how each source is provided. Container MCP is an MCP server BotDojo can run from a catalog template. Featured marks a highlighted catalog entry. BotDojo Index exposes an existing project index as tools. See Connection types for the complete comparison.

Connection settings

The Connection modal is organized around identity, availability, source, tools, and actions.

Identity

Setting	What it does
Name	Sets the label shown in the Connections list, workspace settings, and resource selectors. When agents search for an available Connection, they can see its Name and Description. Use a name that identifies the application, connected account, or purpose.
Icon	Sets the visual marker shown beside the Connection. Select the icon button to choose a different icon.
Description	Explains to users and agents what the Connection is for. Describe the capabilities an agent should use it for and any important limits. Do not place credentials or setup notes here.
URI	Gives the Connection its unique BotDojo address. An agent can use this address to find the Connection and call its tools. BotDojo manages the scope prefix and `/TOOLS.md` suffix; edit the path between them.
Copy URI	Copies the complete URI for use in agent instructions, policies, or another setting that needs to refer to this Connection.

The editable URI path is required and must be unique within its scope. It can use lowercase letters, numbers, hyphens, and slashes. Changing the display name does not require changing the URI. Keep the URI stable after workspaces, flows, policies, or instructions begin referring to it.

The URI prefix identifies the Connection's scope:

URI prefix	Scope
`botdojo://acme/tools/…/TOOLS.md`	An account-shared Connection, using `acme` as the example account alias. Agents in another project or a user's personal workspace can use it when they have permission.
`botdojo://project/tools/…/TOOLS.md`	A project-only Connection that is not shared with the account. It can be used by permitted agents in the project's workspaces and flows.
`botdojo://personal/tools/…/TOOLS.md`	A user's personal Connection. It is available to that user's personal workspaces according to their Connection settings. See Personal Connections.

Every BotDojo resource has its own URI. The URI lets agents and policies refer to a resource without depending on its display name. An agent still needs permission to access the Connection and can call only the tools its policy allows.

Setting	What it does
Enabled by default	When on, users and workspace agents with permission can discover and use the Connection by default. When off, they must explicitly enable it. This changes discovery, not permission.
Share with account	Makes a project Connection available from other projects and personal workspaces in the same account. It does not appear for a personal Connection. Sharing makes the Connection eligible for reuse but does not grant access by itself.
Export as MCP	Makes the Connection available to approved external MCP clients through a BotDojo MCP server URL. Save the Connection before export takes effect.

When Export as MCP has been saved, the modal also shows:

Setting	What it does
MCP Server URL	The endpoint an external MCP client uses to reach this Connection.
Copy external MCP URL	Copies the MCP server endpoint.
Get URL & Token	Opens the setup path for the endpoint and its BotDojo access token. Treat that token as a secret.

Visibility and sharing do not replace runtime access controls. See Connection Access for user and agent permissions, and Shared Connections for account assignment.

Export as MCP

Enable Export as MCP to expose a supported Connection to an approved external MCP client. BotDojo provides an MCP server URL and continues enforcing the Connection's source configuration, enabled tools, approvals, and access controls.

Before distributing the endpoint:

Disable tools the external client does not need.
Give ambiguous tools a clear custom name and description.
Set Deny, Ask, or Allow for each enabled tool.
Set Default Approval for tools discovered later.
Save and verify that tool discovery succeeds.
Select Get URL & Token and put the returned token in the client's secret store.

Do not copy an Integration token, OAuth client secret, bearer token, or source credential into the external client. The client uses the BotDojo endpoint and access token instead. Rotate or revoke that access if the token may have been exposed.

Turn off Export as MCP and save the Connection when external access is no longer required. Remove the endpoint and token from the client as well.

Source

The source panel identifies where the Connection's tools come from. Its contents change with the Connection type.

For an application Connection such as Notion, Integration Source shows the connected Integration, provider, connected account when available, and the provider endpoints used by the Connection. Select Open Integration to review or update the provider authorization. A missing source is shown as Integration not found and must be repaired before tools can refresh.

Remote MCP, container MCP, index, and flow-backed Connections show controls specific to those sources instead. After changing a source or its authorization, refresh and review the tool list.

Tools and approvals

The Tools section is the Connection's contract with agents. It controls which source actions are available, how agents see them, and whether each call is denied, requires approval, or can run immediately.

The Notion Connection tool list with Tool Prefix, bulk approval actions, and enabled tools

Discovery status and Refresh

The Tools header shows:

how many tools were discovered;
how many discovered tools are enabled;
when discovery last completed, or its current status; and
Refresh, which asks the source for its current tool list again.

Use Refresh after the provider adds, removes, or changes tools. Save also refreshes the tool snapshot. After either action, review enablement, names, descriptions, and approvals because the available tool surface may have changed.

Tool Prefix

Tool Prefix prepends the same value to every exposed tool name. Use a short, stable prefix when two Connections expose similar tool names—for example, notion or support. Avoid unnecessary or frequently changing prefixes because agent instructions may refer to the exposed tool names.

Enable or disable tools

The checkbox beside each tool controls whether it is part of the Connection's usable tool surface. Disabling a tool removes it from use regardless of whether its approval is Deny, Ask, or Allow.

Enable only the tools users and agents need. A smaller tool surface is easier to understand and reduces unintended actions.

Tool approvals

Setting	Behavior
Deny	Blocks the tool from running through this Connection.
Ask	Requires approval before the call runs. Use it for consequential actions such as creating, updating, sending, or deleting.
Allow	Lets an identity that already has Connection access call the tool without another tool-level approval.

Use Deny All, Ask All, or Allow All to establish a baseline, then review individual exceptions. Reset to defaults removes Connection-specific approval overrides and returns to the provider defaults; it is unavailable when there is nothing to reset.

Tool approval is one layer of the security boundary:

The user or agent must have access to the Connection.
The tool must be enabled.
The approval policy must permit the call.
A tool set to Ask must receive approval before it runs.

Unattended agents and scheduled work cannot wait for a person unless their workflow supports that approval path. Give unattended work only the tools it needs and a policy it can complete safely.

Customize a tool

Select the pencil action to expand a tool's settings.

An expanded Notion tool with custom name, custom description, enabled state, and approval controls

Setting	What it does
Custom Name	Replaces the provider's name shown to agents. It must be 1–128 characters and use only letters, numbers, underscores, or hyphens.
Custom Description	Replaces the provider description shown to agents. Explain what the tool does, when to use it, and any important boundary.
Reset	Removes that tool's custom name and description and restores the provider values.

A customized tool is marked Customized. Tool names and descriptions guide agent selection, so update prompts and Skills that refer to a tool after renaming it.

Advanced: Default Approval

Open Advanced and set Default Approval to choose the policy assigned to tools discovered in the future.

The Advanced section with Default Approval set to Ask for newly discovered tools

Use Ask or Deny when the source can add consequential tools without notice. Use Allow only when newly added tools can safely run without a person reviewing them. This default does not replace a review after refreshing the source.

Actions

The actions at the bottom of the modal apply after the identity, availability, source, and tool settings above.

Action	What it does
Save	Validates the URI, persists all modal settings, and refreshes the source's tool snapshot. The modal reports whether the settings saved and tool discovery succeeded.
Archive	Asks for confirmation, then removes the Connection from active use. Check workspaces, flows, and shared assignments first.
Close	Closes the modal without applying unsaved edits.

If saving succeeds but tool discovery fails, the Connection remains saved and the modal reports the refresh error. Correct the source and retry the refresh.

Connection types

Every item added from the browser becomes a Connection with the same identity, availability, source, and tool-policy structure. The type determines where its tools and authorization come from.

Type	What it is	Use it when
Application integration	A connected Integration you set up in BotDojo. The Integration holds the provider authorization and credentials; the Connection exposes a controlled set of its tools.	BotDojo lists the application and its native tools. Examples include Notion, Google Drive, Gmail, HubSpot, Salesforce, and Zendesk.
Remote MCP	A Connection to an MCP server hosted outside BotDojo.	A provider or internal service publishes an MCP endpoint.
Container MCP	An MCP server BotDojo can run from a catalog template. Setup may include an Integration sign-in or server-specific configuration.	The catalog implementation supplies the tool surface you need and you want BotDojo to run it.
BotDojo index	Retrieval tools backed by an existing project index.	Agents need to search data already indexed in BotDojo.
Flow-backed Connection	One or more callable tools backed by an existing flow, when available.	A reusable BotDojo flow should become an agent capability.

The type does not decide who can use the Connection. Enabled by default, Share with account, user or agent access, tool enablement, and tool approvals remain separate controls.

Remote MCP Connections

A Remote MCP Connection links the project to an MCP server hosted outside BotDojo. BotDojo uses the selected authentication method, discovers the server's tools, and applies the same identity, visibility, and approval controls as every other Connection.

Create one from Connections → Add Connection → Add Custom Connection.

The Add Custom Connection form for a remote MCP server

Complete the form

Field	What to enter
Auth Type	The authentication method supported by the MCP server.
Connection Name	A clear project-facing name, such as `Internal Support Tools`.
MCP Server URL	The provider's HTTP MCP endpoint, including its MCP path. Do not enter an OAuth install, authorization, or token URL.
Default visibility	Discoverable makes the Connection available by default to identities that have permission. Hidden requires it to be explicitly enabled.

Required fields are validated after you leave a field or try to connect. The connect action remains unavailable until the required values are present.

Choose an authentication type

Auth Type	Use it when
OAuth - Dynamic Client Registration	The server publishes OAuth metadata and supports automatic client registration. BotDojo discovers the metadata, registers a client, opens provider authorization, exchanges the code, and saves the resulting authorization.
OAuth - Pre-registered Client	The provider requires you to create an OAuth or MCP application first. Register the exact Redirect URI shown by BotDojo, then enter the provider's Client ID and Client Secret.
Bearer Token	The server expects a static token in the `Authorization: Bearer …` header. Use the smallest-scope token that can reach the intended tools.
No Authentication	The server is intentionally unauthenticated or already protected by a network boundary you trust. BotDojo sends no authorization header.

For a pre-registered OAuth client, leave Advanced OAuth Settings at their defaults unless the provider requires a specific scope, token endpoint authentication method, authorization endpoint, or token endpoint. A mismatch in the Redirect URI's scheme, host, path, or trailing slash can cause the provider to reject the callback.

For OAuth, select Connect with OAuth and finish authorization in the provider window. For Bearer Token or No Authentication, use the connection test shown by the form. After setup succeeds, open the saved Connection and configure the discovered tools.

Remote MCP troubleshooting

The connect action is unavailable — Complete the Connection Name, MCP Server URL, and all fields required by the selected authentication type.
No access token is available — Restart the OAuth connection and finish the provider authorization window.
Dynamic registration is unsupported — Use OAuth - Pre-registered Client and create an application with the provider.
Token exchange failed — Verify the Redirect URI, client credentials, scopes, and advanced OAuth settings against the provider application.
No tools were found — Confirm that the URL is the MCP endpoint, the credential can list tools, and the server is reachable from BotDojo.

Never place a bearer token, OAuth client secret, or other credential in the Connection name, description, URI, screenshots, or agent instructions.

Advanced: Connections and integrations

Integrations and Connections work together, but they have different jobs:

Integration
Provider credentials
        ↓
Connection
Allowed tools and policy
        ↓
Users and agents

Resource	Responsibility
Integration	Holds the provider authorization and credentials BotDojo uses to communicate with an external application.
Connection	Is the security boundary users and agents work through. It selects the Integration or other source, exposes only enabled tools, and controls visibility, sharing, and Deny, Ask, or Allow behavior.

An application integration is a connected Integration you set up in BotDojo. Users and agents do not use its credential directly; they use a Connection backed by that Integration.

When creating an application Connection, BotDojo first offers eligible existing Integrations. If none exists, the creation flow opens the provider setup, creates an Integration, and then continues to the Connection settings.

This separation lets administrators maintain provider authorization separately from the agent-facing tool policy. One Integration can hold the connected account's credential while the Connection defines the stable URI, discovery, sharing, enabled tools, and approvals that users and agents receive.

Access and troubleshooting

A user or agent cannot find the Connection — Check Enabled by default and whether the identity explicitly enabled it.
The Connection appears but a call is denied — Confirm that the identity has Connection Access, the tool is enabled, and its approval is appropriate.
A shared Connection is unavailable elsewhere — Confirm Share with account is on and that an administrator assigned it through Shared Connections.
Tools are missing or outdated — Open the source, verify its authorization, select Refresh, and review newly discovered tools.
Saving reports a URI conflict — Choose a unique URI path. The same URI cannot identify two Connections in the same scope.
A flow works for an administrator but not another identity — The runtime user or agent needs access to every Connection the flow may invoke.