Connecting Copilot Studio to the Billtrust MCP Server
Overview
This guide walks through adding the Billtrust Reimagine MCP Gateway as an MCP server action in Microsoft Copilot Studio so that a Copilot agent can invoke invoicing and AR analytics tools on behalf of your users.
Before you begin
The following requirements must be met before connecting Copilot Studio to the Billtrust MCP Gateway.
|
Requirement |
Detail |
|---|---|
|
Copilot Studio license |
Microsoft 365 / Copilot Studio standalone. Requires the MCP Actions feature (GA as of 2025). |
|
Network access |
The gateway is internet-accessible over HTTPS. No VPN required. |
|
Billtrust credentials |
Each end-user needs an active Billtrust account. The gateway authenticates users either via corporate SSO (Cognito/SAML) or email + password. |
Step-by-step guide
Step 1: The MCP endpoint URL
Use the multi-tenant MCP endpoint:
|
Environment |
MCP Endpoint |
|---|---|
|
Production |
https://mcp.us.billtrust.com/mcp |
Users log in via an email-first form. The gateway looks up their default tenant automatically.
Step 2: Add the MCP server in Copilot Studio
-
Open Copilot Studio (copilotstudio.microsoft.com).
-
Open or create your agent.
-
Select Actions from the left navigation.
-
Click + Add an action, then choose MCP.
-
Enter https://mcp.us.billtrust.com/mcp in the Server URL field.
-
Click Next.
Copilot Studio fetches the gateway's /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server metadata to discover the OAuth endpoints automatically. No manual OAuth configuration is required. -
Select OAuth 2.0 (user sign-in) when prompted.
Copilot Studio populates the authorization, token, and registration endpoints from the discovery response. -
Click Add connection (or Save).
Copilot Studio performs Dynamic Client Registration with the gateway. This creates an OAuth client entry scoped to this Copilot agent. -
Name the action (e.g. Billtrust AR Tools).
-
Click Save.
The action appears in the Actions list with a Connected status.
Step 3: Verify the available tools
The gateway currently exposes the below tools. Confirm the tool names appear in the action's Tools tab after the connection is saved in Copilot Studio.
|
Tool name |
Description |
|---|---|
|
query_billtrust_data |
Ask an analytical question about your Billtrust accounts receivable data. Returns a written answer grounded in your data. |
Step 4: Test the connection
-
Open the Test your agent panel in Copilot Studio.
-
Enter a test prompt.
Example: Get account details for customer ACME Corp.
The agent invokes invoicing_get_account_detail.
-
On first use, Copilot Studio redirects the user through the gateway's OAuth login flow:
-
SSO tenants are redirected to their corporate IdP (Cognito/SAML). No password entry needed.
-
Non-SSO tenants are prompted to enter their Billtrust email + password.
After sign-in, the token is cached. Subsequent calls within 30 days do not require re-authentication.
Step 5: Grant user access
Once the agent is working within the test panel, you must publish it and share it with the appropriate users before anyone else can use it.
Publish the agent
-
In Copilot Studio, click Publish (top-right of the editor).
-
Confirm the publish details and click Publish again.
Copilot Studio deploys the agent to its hosted endpoint. This step is required before any sharing options become available.
Share with specific users or security groups
-
After publishing, click Share (next to the Publish button, or under Settings > Share).
-
In the Share this agent dialog, enter the Microsoft 365 user email addresses or Azure AD/Entra ID security group names you want to grant access.
-
Set the access level:
-
Users can chat with the agent (most users should get this role).
-
Co-owners can also edit and republish the agent (limit to admins).
-
Click Share.
Invited users receive an email with a link to the agent.
Share with a security group rather than individual users when rolling out to a team. Group membership changes take effect without re-sharing in Copilot Studio.
Deploy to Microsoft Teams (optional)
-
Navigate to Channels in the left navigation of Copilot Studio.
-
Select Microsoft Teams
-
Click Add to Teams.
-
From the Teams Admin Center, go to Teams apps > Manage apps to find the agent and set its availability to the desired users, groups, or the whole organization.
Users can now find and install the agent from the Teams App Store or via a direct link.
Verify each user has a Billtrust account
Access to the agent in Copilot Studio is controlled by Microsoft 365 permissions. Access to the Billtrust data within the agent is controlled by the MCP Gateway's OAuth layer. Every user must also have an active Billtrust account. Before sharing the agent, confirm:
-
The user has an active Billtrust account on the correct tenant.
-
For SSO tenants, the user's Microsoft / Cognito identity is linked to their Billtrust account.
-
For non-SSO tenants, the user knows their Billtrust email + password.
Users without a Billtrust account will be able to open the agent but will see an "Email not recognized" error when the agent first tries to call a Billtrust tool. See the Troubleshooting section below.
Having an active Billtrust account is required but not always sufficient. Tool and domain access is also checked on every request. If a user’s tenant or account is not entitled, the tool may not be available to them even after a successful sign-in.
Technical Reference Guide
OAuth flow details
Understanding the flow helps when troubleshooting sign-in errors.
Copilot Studio MCP Gateway User's browser
| | |
| GET /mcp | |
|--------------------> | 401 WWW-Authenticate|
| Discover well-known | |
|--------------------> | |
| POST /oauth/clients | |
|--------------------> | { client_id, ... } |
| | |
| Redirect to | |
| /authorize | |
|--------------------------------------------->
| | email -> tenant lookup
| | SSO: 302 -> IdP |
| | Password: login form|
| |<---- user signs in --|
| | 302 redirect_uri?code
|<---------------------------------------------
| POST /token | |
|--------------------> | { access_token, ... }
| | |
| POST /mcp | |
|--------------------> | tool result |
Key properties of the gateway's OAuth implementation:
-
Dynamic Client Registration (POST /oauth/clients): Copilot Studio self-registers. No pre-provisioned client_id is needed.
-
PKCE S256: All DCR clients are public (no client_secret). The gateway forces token_endpoint_auth_method: none even if a client requests a secret, to avoid a broken state where the client submits a secret it does not send at /token.
-
Scope: A single scope is required: mcp. No additional scopes are needed for tool access.
-
Session lifetime: 30 days from first sign-in. When a session expires, Copilot Studio triggers a re-authentication flow automatically.
-
Silent token refresh: The gateway transparently refreshes the underlying Billtrust JWT using the user's stored credentials (Cognito refresh token for SSO; encrypted email/password for password sessions). This happens in the background. Users are not re-prompted unless the 30-day cap fires.
Cognito callback URLs
The MCP Gateway registers these callback URLs in each tenant's Cognito App Client (provisioned by sso-service-worker):
|
Environment |
Cognito callback URL |
|---|---|
|
Production |
https://mcp.us.billtrust.com/authorize/callback |
These are managed via the BT_MCP_GATEWAY_CALLBACK_URL SSM parameter in sso-service-worker's Terraform. If SSO sign-in fails with a redirect_mismatch error from Cognito, verify this parameter is set correctly for the environment.
Teams declarative agent (pinned client ID)
If your Copilot agent is a Teams declarative agent configured in the Teams Developer Portal (App ID dfbc7aa0-c842-4aaa-936c-760963f1f76e), the gateway has a static pre-registered OAuth client for it:
|
Field |
Value |
|---|---|
|
client_id |
98dc9db6-fa7a-49e0-93c0-7e1f0b8fcd92 |
|
token_endpoint_auth_method |
none (PKCE) |
|
Registered redirect URIs |
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect https://teams.microsoft.com/v2/oauth/callback https://teams.microsoft.com/callback |
Using this pre-registered client_id means zero DCR calls are needed and the client_id is stable across DB resets and cluster migrations. Configure it in the Teams Developer Portal's OAuth Connection settings:
|
Setting |
Value |
|---|---|
|
Authorization endpoint |
https://mcp.us.billtrust.com/authorize |
|
Token endpoint |
https://mcp.us.billtrust.com/token |
|
Client ID |
98dc9db6-fa7a-49e0-93c0-7e1f0b8fcd92 |
|
Scopes |
mcp |
|
Token exchange URL |
(leave blank) |
The Teams SDK does not support PKCE. The gateway accepts public clients without a code_challenge. The Teams bot broker goes through this no-PKCE path, authenticated by the Teams redirect URI exact-match.
What you can ask
The connector exposes one tool, Query Billtrust AR data (technical name: query_billtrust_data). Ask a natural-language question about your Billtrust accounts receivable data, and Claude returns a written answer grounded in your data.
The tool covers four analytical domains. Which domains are available to you depends on your tenant configuration and your user permissions. Both are checked on every request.
| Domain | Example question |
| AR / Open Balance | “What are our total open receivables right now?” |
| Invoicing | “What is the aging of our invoiced amounts?” |
| Payments | “What is our on-time versus late payment rate this quarter?” |
| Cash Application | “What is our current unapplied cash total?” |
The tool does not have access to Billtrust Collections or Billtrust Credit. If a domain or the tool itself is not enabled for your tenant or user account, it will not appear in Claude, even after you sign in.
Troubleshooting
"Authorization server metadata is invalid" on connect
The gateway's OAuth discovery response must have an issuer that matches the host you connected to (https://mcp.us.billtrust.com ). If you see this error, verify:
-
You are using https:// (not http://).
-
The URL ends in /mcp — omitting the path causes the well-known handler to return a 404.
Run the probe script against the nonprod gateway to reproduce the full discovery chain locally:
bun mcp-gateway/scripts/probe.ts https://mcp.us.billtrust.com
User sees "Email not recognized" during sign-in
The email entered does not have an Billtrust account on this tenant. Confirm the user exists in Billtrust and their account is active.
User sees "Workspace unavailable"
The workspace resolved from the user's email is not accessible. Confirm the user's Billtrust account is active and associated with the correct tenant.
"Session expired — reconnect" after 30 days
Expected behavior. The 30-day session cap fired. The user needs to re-authenticate. Copilot Studio triggers this automatically on the next tool call that returns 401 invalid_token.
SSO redirect_mismatch from Cognito
The Cognito App Client's registered callback URL does not match what the gateway sends. The gateway sends {issuer}/authorize/callback. Verify the BT_MCP_GATEWAY_CALLBACK_URL SSM parameter in sso-service-worker matches the gateway's deployed issuer URL for this environment.
SSO redirect goes to password form instead of IdP
The gateway falls through to the password form when SERVICE_ACCOUNT_API_KEY is not configured or sso-service returns no active SSO config for the tenant. Contact your Billtrust platform team to verify the secret is provisioned and the tenant's SSO configuration is active.
query_billtrust_data tool not visible
The data analytics tool is only registered when DATA_AGENT_MCP_URL is set in the gateway's environment. Confirm with your Billtrust platform team whether the slim data-agent service is deployed and the env var is wired up for this environment.
Privacy and support
For details on how Billtrust collects, uses, stores, and retains data, see the Billtrust privacy policy at https://www.billtrust.com/legal/privacy-policy.
For questions or issues, contact Billtrust support at support@billtrust.com.