OAuth Setup

This guide walks you through connecting to a Timbr MCP server that uses OAuth 2.0 authentication. The Timbr MCP server lets AI tools (Claude, Cursor, MCP Inspector, etc.) query your data using natural language.

Prerequisites

A Timbr deployment with MCP OAuth enabled (ask your Timbr admin)
Your Timbr server URL (e.g., https://your-env.com/timbr/api/mcp)
Access to Azure AD (or your organization's identity provider)

Quick Start

Step 1: Get Your Server URL

Your MCP server URL follows this pattern:

https://<your-timbr-host>/timbr/api/mcp

For example: https://example.com/timbr/api/mcp

Step 2: Choose Your MCP Client

MCP Inspector - browser-based testing tool
Claude.ai Custom Connectors - Anthropic's Claude web interface
Claude Desktop - Claude desktop application
Cursor - AI-powered IDE
Microsoft Copilot Studio - Microsoft's AI agent builder

MCP Inspector

The MCP Inspector is a browser-based tool for testing MCP servers.

Setup

Open MCP Inspector in your browser
Set Transport Type to Streamable HTTP
Enter your server URL: https://<your-timbr-host>/timbr/api/mcp
In Authentication Settings:
- Choose OAuth authentication
- Set Client ID: your Azure AD client app ID (get this from your admin)
- Set Client Secret: your Azure AD client app secret
- Set Scope: api://<resource-app-id>/.default
Click Connect

What Happens

MCP Inspector connects to your server
The server returns 401 Unauthorized with discovery information
MCP Inspector discovers the OAuth endpoints automatically
You're redirected to your organization's login page (For example: Azure AD)
After login, the token is exchanged and you're connected
You can now list and call tools (query_data, ask_question, generate_sql, identify_concept)

Troubleshooting

Error	Cause	Fix
`Failed to fetch`	CORS issue	Check browser console for blocked headers. Contact your Timbr admin.
`AADSTS9010010`	Scope/resource mismatch	Verify the scope format: `api://<resource-app-id>/.default`
`AADSTS90009`	Same app as client and resource	You need a separate client app registration (see Azure AD Setup below)
`Protected resource X does not match expected Y`	Server URL mismatch	Verify `MCP_OAUTH_RESOURCE_URL` environment variable in `timbr-api` service matches your external URL
`invalid_client`	Wrong client credentials	Check client_id and client_secret

Claude.ai Custom Connectors

Claude.ai supports custom MCP connectors with OAuth authentication.

Setup

Go to Claude.ai → Settings → Connectors (or equivalent)
Click Add Custom Connector
Give a name to the connector, i.e. - Timbr Semantic Layer
Enter the MCP server URL: https://<your-timbr-host>/timbr/api/mcp
Click on the Advance Settings link
- Set Client ID: i.e. - your Azure AD client app ID (get this from your admin)
- Set Client Secret: i.e. - your Azure AD client app secret
Claude.ai will automatically discover the OAuth endpoints
You'll be redirected to your organization's login page
After login, the connector is ready to use
- Optional: You can click on the Configure link of the connector to adjust the tools settings.

Requirements for Azure AD

For Claude.ai custom connectors to work with you Azure AD setup, your Timbr admin needs to:

Create a dedicated Azure AD client app for Claude.ai:
- Register a new app in Azure Portal
- Add redirect URI: check Claude.ai docs for the exact callback URL, for example: https://claude.ai/api/mcp/auth_callback
- Create a client secret
- Grant API permissions for the Timbr resource app
Or enable Dynamic Client Registration (DCR) - set MCP_OAUTH_DCR_ENABLED=true with MCP_OAUTH_CLIENT_ID and MCP_OAUTH_CLIENT_SECRET so the Timbr server handles registration locally (Azure AD does not natively support DCR)

Troubleshooting

Error	Cause	Fix
`AADSTS90009`	No separate client app	Create a dedicated Azure AD app registration for Claude
Redirect to wrong URL	AS metadata misconfigured	Admin: verify `curl https://<host>/.well-known/oauth-authorization-server` returns correct URLs
`Failed to discover OAuth metadata`	Well-known endpoints unreachable	Admin: verify ingress rules for `/.well-known/` paths

Claude Desktop

Setup

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "timbr": {
      "url": "https://<your-timbr-host>/timbr/api/mcp",
      "transport": "streamableHttp"
    }
  }
}

Claude Desktop will handle OAuth discovery and authentication automatically. You'll be prompted to log in via your organization's identity provider on first connection.

Cursor

Setup

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "timbr": {
      "url": "https://<your-timbr-host>/timbr/api/mcp",
      "transport": "streamableHttp"
    }
  }
}

Cursor will handle OAuth discovery and authentication automatically.

Microsoft Copilot Studio

Microsoft Copilot Studio supports MCP servers via the MCP onboarding wizard or custom connectors.

Copilot Studio MCP Requirements

Streamable HTTP transport only (SSE is not supported after August 2025)
Generative Orchestration must be enabled in your Copilot Studio agent
Tool input schemas must not use $ref types (these are filtered out by Copilot Studio)

Prerequisites

Dynamic Client Registration (DCR) must be enabled on the Timbr server
An Azure AD app registration for the Timbr MCP resource (see Azure AD Setup)

Required Server Configuration

Your Timbr admin needs to configure DCR with pre-registered Azure AD credentials:

MCP_OAUTH_ENABLED=true
MCP_OAUTH_DCR_ENABLED=true
MCP_OAUTH_CLIENT_ID=<azure-ad-client-app-id>
MCP_OAUTH_CLIENT_SECRET=<azure-ad-client-app-secret>

This allows Copilot Studio to dynamically register as an OAuth client. Azure AD does not natively support DCR, so the Timbr server handles registration locally and returns the pre-configured credentials during the registration handshake.

Setup (MCP Onboarding Wizard)

The recommended way to connect Copilot Studio to the Timbr MCP server:

Go to your agent's Tools page
Select Add a tool → New tool → Model Context Protocol
Fill in:
- Server name: e.g., Timbr Semantic Layer
- Server description: e.g., Query the Timbr knowledge graph using natural language
- Server URL: https://<your-timbr-host>/timbr/api/mcp
Select OAuth 2.0 authentication → Dynamic discovery
Select Create
Complete the OAuth sign-in flow when prompted. Note: The first connection attempt will fail until you add the Redirect URI that Copilot Studio provides to your OAuth provider configuration.
Select Add to agent - the MCP tools will appear in your agent's Tools tab

Adding Default Headers (x-agent, x-ontology)

The MCP onboarding wizard does not expose Timbr-specific headers like x-agent or x-ontology in the auto-generated connector. To set default values (e.g., always target a specific agent), you need to edit the connector in Power Apps after creation:

Go to Power Apps or Power Automate
In the left navigation, select More → Discover all → Custom connectors
Find your Timbr MCP connector in the list and select Edit (pencil icon)
Go to the Definition tab
Under the InvokeServer action (or your operation), select Import from sample:
- Verb: POST
- URL: https://<your-timbr-host>/timbr/api/mcp
- Headers: x-agent x-ontology
Click Import - the headers appear as parameters
For each parameter, set:
- Default value: e.g., sales_agent for x-agent
- Is required: No
- Visibility: internal (if you want to hide it from users)
Select Update connector to save

After saving, go back to Copilot Studio. The headers now appear as configurable Inputs on the tool's settings page, where you can set or override their values.

tip

You can also add x-ontology the same way if you want to target a specific knowledge graph by default.

Swagger File (Manual Setup)

Manual Setup with DCR (Dynamic Client Registration)

You can create a custom connector manually using a Swagger file. This approach also lets you pre-define the x-agent and x-ontology headers:

swagger: '2.0'
info:
  title: Timbr MCP Server
  description: MCP Server for the Timbr Semantic Layer
  version: 1.0.0
host: <your-timbr-host>
basePath: /
schemes:
  - https
paths:
  /timbr/api/mcp:
    post:
      parameters:
        - name: x-agent
          in: header
          type: string
          default: <your-agent-name>
          description: Pre-configured agent name
          required: false
        - name: x-ontology
          in: header
          type: string
          description: Target ontology name
          required: false
      responses:
        '200':
          description: Immediate Response
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeServer
      summary: Timbr MCP Server
      description: MCP Server for the Timbr Semantic Layer
securityDefinitions: {}
security: []

Replace <your-timbr-host>, <resource-app-client-id>, and <your-agent-name> with your actual values.

To import:

Go to Power Apps → Custom connectors → New custom connector → Import OpenAPI file
Upload the YAML file and complete the setup
Return to Copilot Studio and add the connector as a tool to your agent

Manual Setup without DCR

If dynamic discovery is not available, you can create a custom connector manually using a Swagger file. This approach also lets you pre-define the x-agent and x-ontology headers:

swagger: '2.0'
info:
  title: Timbr MCP Server
  description: MCP Server for the Timbr Semantic Layer
  version: 1.0.0
host: <your-timbr-host>
basePath: /
schemes:
  - https
paths:
  /timbr/api/mcp:
    post:
      parameters:
        - name: x-agent
          in: header
          type: string
          default: <your-agent-name>
          description: Pre-configured agent name
          required: false
        - name: x-ontology
          in: header
          type: string
          description: Target ontology name
          required: false
      responses:
        '200':
          description: Immediate Response
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeServer
      summary: Timbr MCP Server
      description: MCP Server for the Timbr Semantic Layer
securityDefinitions:
  oauth2-auth:
    type: oauth2
    flow: accessCode
    tokenUrl: https://<your-timbr-host>/timbr/api/oauth/token
    authorizationUrl: https://<your-timbr-host>/timbr/api/oauth/authorize
    scopes:
      api://<resource-app-client-id>/.default: api://<resource-app-client-id>/.default
security:
  - oauth2-auth:
      - api://<resource-app-client-id>/.default

Replace <your-timbr-host>, <resource-app-client-id>, and <your-agent-name> with your actual values.

To import:

Go to Power Apps → Custom connectors → New custom connector → Import OpenAPI file
Upload the YAML file and complete the setup
Return to Copilot Studio and add the connector as a tool to your agent

Troubleshooting

Error	Cause	Fix
`GetDynamicClientRegistrationResultAsync failed: NotFound`	DCR not enabled or missing credentials	Set `MCP_OAUTH_DCR_ENABLED=true` and configure `MCP_OAUTH_CLIENT_ID` + `MCP_OAUTH_CLIENT_SECRET`
`Signature verification failed`	JWKS/audience/issuer mismatch	Verify `MCP_OAUTH_JWKS_URL`, `MCP_OAUTH_AUDIENCE`, and `MCP_OAUTH_ISSUER` match your Azure AD tenant
Tools not showing after connection	Connector created but no tools visible	Ensure Timbr API Service is v4.4.4+ which returns plain JSON for `tools/list`
Tool inputs not visible in UI	Copilot Studio does not expose MCP tool `inputSchema` parameters	This is expected - add `x-agent`/`x-ontology` headers via Power Apps custom connector editor (see above)
`AADSTS9010010`	`resource` parameter sent to Azure AD	The Timbr OAuth proxy should strip this automatically; verify proxy is working
Agent doesn't collect inputs during chat	Orchestrator can't extract tool parameters	Add detailed descriptions to your agent's system instructions (e.g., "Always pass `agent_name: sales_agent`")

Available Tools

Once connected, you have access to these tools:

AI Query Tools

Tool	Description	Example
`query_data`	Execute a natural language query and return results	"Show me all customers from New York"
`ask_question`	Execute a query and get an LLM-generated answer	"How many orders were placed last month?"
`generate_sql`	Generate SQL without executing	"Write SQL to find top 10 products by revenue"
`identify_concept`	Identify the relevant table/concept for a query	"What table has customer information?"

Metadata & Exploration Tools

Tool	Description	Example
`execute_sql`	Execute a raw Timbr SQL query	`SELECT * FROM dtimbr.person LIMIT 10`
`list_ontologies`	List all available knowledge graphs	"What knowledge graphs are available?"
`list_agents`	List all pre-configured agents	"Show me available agents"
`list_datasources`	List datasources (all or by knowledge graph)	"What datasources does this ontology have?"
`describe_knowledge_graph`	Get schema metadata (concepts, properties, relationships)	"Describe the sales ontology"

Tool Parameters

All AI query tools accept:

prompt (required) - your natural language query
ontology - the Timbr ontology to query (can also be set via x-timbr-ontology header or URL path)
agent_name - pre-configured agent name (can also be set via x-agent header)
verbose - set to true for detailed response including column metadata

Azure AD Setup (For Admins)

If you're the Timbr administrator setting up OAuth for the first time:

1. Create the Resource App (Timbr API)

This app represents the Timbr MCP server:

Azure Portal → App Registrations → New Registration
- Name: Timbr MCP API (or similar)
- Supported account types: Single tenant
Expose an API:
- Set Application ID URI: api://<app-id>
- Add scope: session:scope:analyst (or your preferred scope name)
Note the Application (client) ID - this is your resource app ID

2. Create Client Apps

Create one app per MCP client type that needs access:

For MCP Inspector / testing:

New Registration → Name: MCP Test Client
Authentication → Add platform → Single-page application
Redirect URI: http://localhost:6274/oauth/callback
Certificates & Secrets → New client secret
API Permissions → Add permission → My APIs → Timbr MCP API → Select scopes

For Claude.ai:

New Registration → Name: Claude MCP Client
Authentication → Add platform → Web
Redirect URI: check Claude.ai documentation for the callback URL
Certificates & Secrets → New client secret
API Permissions → Add permission → My APIs → Timbr MCP API → Select scopes
Grant admin consent if required

3. Configure Timbr Environment Variables

# Required
MCP_OAUTH_ENABLED=true
MCP_OAUTH_RESOURCE_URL=https://your-timbr-host.com

# Azure AD (auto-derived from JWT config if not set)
MCP_OAUTH_AUTHORIZATION_SERVER=https://login.microsoftonline.com/<tenant-id>/v2.0
MCP_OAUTH_JWKS_URL=https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
MCP_OAUTH_AUDIENCE=<resource-app-client-id>
MCP_OAUTH_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0

# Scopes advertised to MCP clients
MCP_OAUTH_SCOPES=api://<resource-app-client-id>/.default

# Dynamic Client Registration (required for Copilot Studio)
MCP_OAUTH_DCR_ENABLED=true
MCP_OAUTH_CLIENT_ID=<azure-ad-client-app-id>
MCP_OAUTH_CLIENT_SECRET=<azure-ad-client-app-secret>

4. Configure Ingress (AKS/nginx)

Optional Section (Configure Ingress)

The following ingress configuration is required only if the timbr-api-service is deployed as a path within the timbr-platform-service. Otherwise, you can skip this section.

Add these paths to your ingress rules, pointing to the API service:

- path: /.well-known/oauth-protected-resource
  pathType: Prefix
  backend:
    service:
      name: timbr-api-<env>
      port:
        number: 9000
- path: /.well-known/oauth-authorization-server
  pathType: Prefix
  backend:
    service:
      name: timbr-api-<env>
      port:
        number: 9000
- path: /.well-known/openid-configuration
  pathType: Prefix
  backend:
    service:
      name: timbr-api-<env>
      port:
        number: 9000

5. Verify Deployment

# Check PRM endpoint
curl https://your-host/.well-known/oauth-protected-resource
# Should return JSON with authorization_servers and scopes_supported

# Check AS metadata
curl https://your-host/.well-known/oauth-authorization-server
# Should return JSON with authorization_endpoint pointing to /timbr/api/oauth/authorize

# Check the authorization_endpoint uses correct scheme
curl -s https://your-host/.well-known/oauth-authorization-server | jq .authorization_endpoint
# Should be: "https://your-host/timbr/api/oauth/authorize" (https, not http)

How Authentication Works

Your MCP client connects to the Timbr server
Server responds: "You need to authenticate" (HTTP 401)
Client discovers OAuth endpoints automatically (RFC 9728)
Client redirects you to your organization's login page
You log in with your corporate credentials
Azure AD issues a token
Client sends the token with every request
Server validates the token and maps your identity to a Timbr user
Your queries run with your Timbr permissions

The token contains your identity (email/UPN). The Timbr server maps this to your Timbr user account and applies your permissions. You can only access data you're authorized to see in Timbr.

Security Notes

Tokens are validated via JWKS (public key verification) - the Timbr server never sees your password
Tokens expire (typically 1 hour) - your client refreshes them automatically
All communication should be over HTTPS
The Timbr server acts as a proxy for the OAuth flow - it strips internal parameters but never stores tokens
Your Timbr admin can disable OAuth at any time by setting MCP_OAUTH_ENABLED=false

OAuth Setup

Prerequisites​

Quick Start​

Step 1: Get Your Server URL​

Step 2: Choose Your MCP Client​

MCP Inspector​

Setup​

What Happens​

Troubleshooting​

Claude.ai Custom Connectors​

Setup​

Requirements for Azure AD​

Troubleshooting​

Claude Desktop​

Setup​

Cursor​

Setup​

Microsoft Copilot Studio​

Prerequisites​

Required Server Configuration​

Setup (MCP Onboarding Wizard)​

Adding Default Headers (x-agent, x-ontology)​

Swagger File (Manual Setup)​

Manual Setup with DCR (Dynamic Client Registration)​

Manual Setup without DCR​

Troubleshooting​

Available Tools​

AI Query Tools​

Metadata & Exploration Tools​

Tool Parameters​

Azure AD Setup (For Admins)​

1. Create the Resource App (Timbr API)​

2. Create Client Apps​

For MCP Inspector / testing:​

For Claude.ai:​

3. Configure Timbr Environment Variables​

4. Configure Ingress (AKS/nginx)​

5. Verify Deployment​

How Authentication Works​

Security Notes​

Prerequisites

Quick Start

Step 1: Get Your Server URL

Step 2: Choose Your MCP Client

MCP Inspector

Setup

What Happens

Troubleshooting

Claude.ai Custom Connectors

Setup

Requirements for Azure AD

Troubleshooting

Claude Desktop

Setup

Cursor

Setup

Microsoft Copilot Studio

Prerequisites

Required Server Configuration

Setup (MCP Onboarding Wizard)

Adding Default Headers (x-agent, x-ontology)

Swagger File (Manual Setup)

Manual Setup with DCR (Dynamic Client Registration)

Manual Setup without DCR

Troubleshooting

Available Tools

AI Query Tools

Metadata & Exploration Tools

Tool Parameters

Azure AD Setup (For Admins)

1. Create the Resource App (Timbr API)

2. Create Client Apps

For MCP Inspector / testing:

For Claude.ai:

3. Configure Timbr Environment Variables

4. Configure Ingress (AKS/nginx)

5. Verify Deployment

How Authentication Works

Security Notes