📘 This article explains how to connect your AI assistant to the Botify MCP when you cannot use an tool's automated connection. Connecting to the Botify MCP is available on any Botify plan.

Overview

Connecting most tools to the Botify MCP is a straightforward, automated process through the designated tool. This article provides guidance for connecting from platforms that require manually registering an OAuth client, using Microsoft 365 Copilot as an example.

⚠️ Since these examples are for a third-party application, ensure you refer to the tool's documentation in addition to the guidance in this article.

There are two types of OAuth client:

Confidential: This type is confidential because it uses a client secret. We recommend using this type when possible.
Public: If your organization prohibits client secrets, you can use a public client, which relies on Proof Key for Code Exchange (PKCE) alone.

Step 1: Create a confidential Botify OAuth client

This method creates a private client that has a secret. Microsoft sends the secret with PKCE whenever it exchanges a sign-in code for tokens. This adds a second check on top of PKCE, and it is the setup the Teams Developer Portal form expects.

👀 Refer to Creating a public OAuth client if your organization prohibits client secrets.

To create a confidential Botify OAuth client, run the following from any terminal. This call does not require a Botify login:

curl -sS -X POST https://app.botify.com/oauth/register/ \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "<Your application name>",
    "redirect_uris": ["https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

👉 The redirect_uris field above is specific to Microsoft 365 Copilot. If you are following this guide for a different tool, refer to the tool's documentation for its redirect_uris.

The response looks like this:

{
  "client_id": "…",
  "client_secret": "…",
  "registration_access_token": "…",
  "registration_client_uri": "https://app.botify.com/oauth/register/…/",
  …
}

Save the whole response somewhere safe, such as a password manager, because you will not see client_secret or registration_access_token again.

You need client_id and client_secret to register the client.
You need registration_access_token and registration_client_uri only if you later want to update or delete this client.

Step 2: Register the client in the Teams Developer Portal

Open https://dev.teams.microsoft.com/tools.
Go to Tools > OAuth client registration.
Click Register client, or New OAuth client registration if you already have existing registrations.
Fill in the form using the fields below, then click Save.
Copy the OAuth client registration ID to use in Step 3.

Field	Value
Registration name	`Botify MCP`, or a name of your choice.
Base URL	`https://mcp.botify.com/`
Restrict usage by org	Your organization, or any Microsoft 365 organization if several tenants need it.
Restrict usage by app	Any Teams app. Selecting a specific app ID causes every tool call to fail with a 404 error.
Client ID	`client_id` from Step 1.
Client secret	`client_secret` from Step 1.
Authorization endpoint	`https://app.botify.com/oauth/authorize`
Token endpoint	`https://app.botify.com/oauth/token/`
Refresh endpoint	`https://app.botify.com/oauth/token/`
Scope	`mcp_read_write`
PKCE	Leave it enabled; Botify requires it.

👉 All other OAuth settings (endpoints, scopes, supported authentication methods, PKCE methods) are published in Botify's standard OAuth discovery document. If a tool asks for a value this article does not include, look there first.

Step 3: Finish the connection

In Copilot (or other tool):

In the "Connect to MCP server" dialog, set the following:
1. Authentication type: OAuth 2.0
2. Reference ID: The OAuth client registration ID from Step 2.
Click Authorize. Botify opens so you can sign in and approve the MCP access.

Create a public OAuth client

If you need to use a public client, which relies on PKCE alone, make the following changes to the instructions above:

In Step 1, set "token_endpoint_auth_method" to "none":

curl -sS -X POST https://app.botify.com/oauth/register/ \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "<Your application name>",
    "redirect_uris": ["https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

The response has no client_secret. You still need to save registration_access_token.

In Step 2, leave Client secret empty and keep PKCE enabled, which is mandatory here. If the portal will not save without a client secret, do not invent a value: Botify would reject it when a user signs in. Use the confidential setup above instead.

Botify OAuth Client Management

Botify removes an OAuth client after 30 days without use. A connection that stays in use is never removed. If the client gets deleted for inactivity, repeat the steps above.
Sessions expire after 90 days of inactivity. A user who has not used the connection for 90 days is prompted to sign in again.

Viewing or deleting the client

To update or delete a client, run the following from any terminal:

# View
curl -sS -H "Authorization: Bearer <registration_access_token>" <registration_client_uri>
# Delete
curl -sS -X DELETE -H "Authorization: Bearer <registration_access_token>" <registration_client_uri>

See also:

Manually Connecting to the Botify MCP with OAuth