MCP Connector¶

The CertifyClouds MCP Connector lets approved hosted AI clients query your CertifyClouds deployment over the Model Context Protocol (MCP). It is designed for security teams that want natural-language access to expiry, asset, dependency, compliance, and audit data without exposing secret values or granting write access.

CertifyClouds is the MCP resource server. Your Microsoft Entra ID tenant remains the OAuth authorization server. CertifyClouds validates Entra-issued bearer tokens on every MCP request and then applies its own license, role, tenant-scope, tool-policy, audit, and redaction rules.

What Phase 1 Provides¶

Phase 1 exposes these read-only MCP tools:

There are no write tools in Phase 1. Do not create, grant, or document Mcp.Rotation.Write, Mcp.Discovery.Write, rotation execution tools, or credential-rotation claims for this release.

Architecture¶

AI client -> public HTTPS CertifyClouds MCP endpoint -> Entra token validation
         -> CertifyClouds user mapping, tenant scope, tool policy, audit

1. A user connects an AI client to https://<your-certifyclouds-host>/api/mcp.
2. The client discovers CertifyClouds protected-resource metadata at /.well-known/oauth-protected-resource.
3. The metadata points the client to your Entra tenant as the authorization server.
4. The user signs in with Entra. MFA, Conditional Access, PIM, sign-in logs, and tenant revocation remain under your control.
5. Entra issues a v2 access token whose aud claim identifies the MCP API. For the standard api://<resource-app-client-id> setup, this is normally the API app's Application (client) ID GUID.
6. CertifyClouds validates iss, tid, aud, signature, expiry, token version, scopes, and accepted client ID on every request.
7. CertifyClouds maps the Entra identity to an existing CertifyClouds user. Unmapped users are rejected.
8. The requested tool runs only inside the caller's allowed tenant scope and is written to the CertifyClouds audit log.

CertifyClouds never issues OAuth tokens for the AI client, never stores third-party access tokens, never stores refresh tokens, and never forwards the received bearer token to Azure or any other system.

Customer-authorized data flow¶

MCP is an optional external data path. When an administrator enables the connector and a user invokes a tool from a hosted AI client, CertifyClouds returns the selected read-only result metadata over TLS to that customer-chosen provider. Depending on the tool, this can include asset names and identifiers, expiry metadata, dependency relationships, compliance findings, or scoped audit events.

CertifyClouds-operated services do not receive those MCP results. The hosted provider processes them under the customer's agreement and configuration with that provider. Secret values, bearer tokens, private keys, certificate material, and value-shaped hints are never returned by Phase 1 tools.

Prerequisites¶

CertifyClouds¶

• ENTERPRISE license with MCP enabled.
• A stable public HTTPS URL for the deployment, for example https://certifyclouds.example.com.
• APP_BASE_URL set to the same public URL in Settings -> Network or as the APP_BASE_URL environment variable.
• Existing CertifyClouds users mapped to Entra identities. Phase 1 does not auto-provision users.
• Admin access to Settings -> MCP Connector for trusted issuer, client policy, and diagnostic setup.

Network¶

AI clients run from vendor infrastructure, not your browser. They must be able to reach:

• https://<your-certifyclouds-host>/.well-known/oauth-protected-resource
• https://<your-certifyclouds-host>/.well-known/oauth-protected-resource/api/mcp if the client requests the path-aware RFC 9728 metadata alias
• https://<your-certifyclouds-host>/api/mcp
• https://<your-certifyclouds-host>/health if you use it as an external readiness check

The endpoint must use publicly trusted TLS. Self-signed certificates, raw IP URLs, and private-only hostnames are not supported for remote AI clients.

If the deployment is behind Cloudflare Access, Azure Front Door, Application Gateway, API Management, or another gateway, configure the gateway so the MCP paths are reachable by the AI client:

The MCP connector uses the existing CertifyClouds application route. Do not create a separate MCP service or hostname unless your CertifyClouds deployment itself is moving there. Cloudflare, Azure Front Door, Application Gateway, and API Management should route /.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/api/mcp, and /api/mcp to the same CertifyClouds backend and preserve:

• Authorization
• MCP-Protocol-Version
• MCP-Session-Id
• Content-Type
• POST bodies

For Cloudflare Access specifically, use a path-bypass or service-auth design for the MCP paths. A browser-only Access policy will block Claude and ChatGPT before CertifyClouds can return OAuth metadata or validate the Entra token.

Do not bypass CertifyClouds authentication. The path bypass is only for the outer access proxy. CertifyClouds must still validate the Entra bearer token on every /api/mcp request.

Reverse proxy and Cloudflare troubleshooting¶

If a hosted client fails before the Entra sign-in page, first determine whether the request reached CertifyClouds at all. A CertifyClouds response for MCP is JSON-RPC, RFC 9728 metadata, or a typed OAuth/MCP error. An HTML block page, Cloudflare challenge, Access login page, or AI Labyrinth honeypot response is generated at the edge; CertifyClouds has not received the request and cannot validate the token or write an auth-failure audit row.

For Cloudflare zones:

1. Open Security -> Events for the deployment hostname and filter the timeframe around the connector attempt.
2. Filter or search for the hosted-client user agent, especially Claude-User for Claude.ai custom connectors. ChatGPT traffic may appear separately as ChatGPT-User.
3. Check which product produced the action. Bot Fight Mode is separate from Cloudflare's AI bot and AI crawler controls; turning Bot Fight Mode off does not prove that AI bot rules are allowing a hosted connector.
4. If Claude-User is blocked as AI crawler/assistant/agent traffic, allow user-directed Agent traffic where your plan exposes Cloudflare's current AI bot taxonomy. If the plan supports path-scoped rules, prefer a narrowly scoped exception for the exact MCP transport and metadata paths only:
5. /.well-known/oauth-protected-resource
6. /.well-known/oauth-protected-resource/api/mcp
7. /api/mcp
8. Do not add a broad /api/* bypass. Normal CertifyClouds browser/API routes should keep the customer's main Access/WAF policy.

Cloudflare's July 2026 AI bot taxonomy separates Agent traffic, which is automated activity acting for a user, from Training crawlers and Search crawlers. See Cloudflare's current docs for Block AI Bots, Verified bots, AI Crawl Control, and AI Labyrinth. If your zone only has the legacy global Block AI bots switch, allowing it may also reduce training-crawler blocking because the older switch is not path- or behavior-specific. In that case, prefer a plan-supported path exception or custom WAF rule for the MCP paths; if you must change only the global legacy switch, record the training-crawler tradeoff with the customer's security owner before enabling hosted connectors.

Do not make Anthropic or OpenAI source IP ranges the primary security boundary. Vendor IP observations can help diagnose whether traffic is reaching Cloudflare, but hosted-client egress can change and multiple customers may share the same infrastructure. The durable boundary is still: edge allows only the required public MCP paths, then CertifyClouds validates the Entra JWT, issuer, audience, client ID, scopes, mapped user, tenant scope, and tool policy on every request.

Capacity Behavior¶

MCP is optional read-only traffic. During busy periods, the connector can return retryable 429 or 503 responses. Clients should honor Retry-After and use bounded retries rather than increasing concurrency.

MCP POST bodies are limited to 1 MiB and JSON-RPC batches are limited to 25 messages. Requests above either limit are rejected.

Entra Setup¶

Create a resource API App Registration and one client App Registration per approved hosted AI surface:

• CertifyClouds MCP API (Production): a single-tenant resource API app that represents your CertifyClouds MCP resource server.
• CertifyClouds MCP Client - Claude Web (Production): a single-tenant confidential web client used by the Claude custom connector, when approved.
• CertifyClouds MCP Client - ChatGPT (Production): a separate single-tenant confidential web client used by the ChatGPT developer-mode app, when approved.

Do not create client registrations for surfaces your organization has not approved.

Use this naming standard so API and client objects are unambiguous:

CertifyClouds <Capability> <ObjectType> - <Qualifier> (<Environment>)

Recommended Production names:

• CertifyClouds MCP API (Production)
• CertifyClouds MCP Client - Claude Web (Production)
• CertifyClouds MCP Client - ChatGPT (Production)

Supported setup helper¶

The CertifyClouds deployment package includes a preview-first Entra setup helper. Run it from an administrator workstation that has Azure CLI and jq installed. Sign in to the customer tenant first:

az login --tenant <tenant-id> --allow-no-subscriptions

./scripts/deploy/setup-mcp-connector.sh \
  --tenant <tenant-id> \
  --host https://<your-certifyclouds-host> \
  --client claude

Preview is the default and makes no Entra changes. Review the tenant, public resource URL, registration names, callback, and read-only scopes, then rerun the same command with --apply. The active Azure CLI tenant must exactly match --tenant.

For ChatGPT, select a separate client and provide the exact callback shown in the current ChatGPT app setup flow:

./scripts/deploy/setup-mcp-connector.sh \
  --tenant <tenant-id> \
  --host https://<your-certifyclouds-host> \
  --client chatgpt \
  --chatgpt-redirect-uri https://<exact-callback-from-chatgpt> \
  --apply

Repeat --client to configure both hosted clients in one run. Add --with-audit only for clients approved to receive Mcp.Audit.Read.

The helper creates or reuses the resource API, one confidential client per selected hosted surface, their service principals, delegated permissions, admin consent, and an append-only managed client secret. New secret values are shown once on the administrator's terminal and are not written to the script transcript. An identical rerun keeps the current managed secret. Use --renew-client-secrets only when deliberately rotating the selected clients; it appends replacements and does not delete existing credentials.

The helper does not change CertifyClouds settings, enable the connector, change Cloudflare or another edge provider, or acquire a user access token. Complete those steps separately below. If the helper cannot be used, follow the manual registration steps in the next sections.

1. Register the CertifyClouds MCP API¶

1. Go to Microsoft Entra ID -> App registrations -> New registration.
2. Name it CertifyClouds MCP API (Production).
3. Supported account types: Accounts in this organizational directory only.
4. Do not add a redirect URI to the API app.
5. Open Expose an API.
6. Set the Application ID URI to the deployment's exact public MCP resource URL: https://<your-certifyclouds-host>/api/mcp. The hostname must be a verified custom domain in your Entra tenant.
7. Open Manifest and set requestedAccessTokenVersion to 2.
8. Add these delegated scopes exactly:

Do not add write scopes for Phase 1.

The full OAuth scope identifiers are the Application ID URI plus the scope name, for example https://<your-certifyclouds-host>/api/mcp/Mcp.Assets.Read. CertifyClouds publishes these resource-qualified values in RFC 9728 metadata so clients that send an RFC 8707 resource parameter remain compatible with Entra.

2. Register each approved hosted client¶

Create a distinct client registration for each approved hosted client. This keeps callback URIs, secrets, revocation, sign-in logs, and CertifyClouds client policies attributable to one vendor surface.

1. Create the App Registration using the matching Production name above.
2. Supported account types: Accounts in this organizational directory only.
3. Add the exact Web redirect URI required by the client:
4. Claude currently publishes https://claude.ai/api/mcp/auth_callback.
5. ChatGPT generates a setup-specific callback URI. Copy it from the current app setup flow; do not guess it or reuse the Claude callback.
6. Create a separate client secret for each hosted-client registration. Entra does not provide Dynamic Client Registration for this setup, so the vendor needs the configured client ID and secret.
7. Copy the secret value into that vendor's connector UI only. Do not paste it into tickets, documentation, logs, or CertifyClouds diagnostics.
8. Open API permissions -> Add a permission -> My APIs -> CertifyClouds MCP API (Production).
9. Select only the Phase 1 delegated scopes required for the connector.
10. Click Grant admin consent. Users should not self-consent to MCP scopes.

Do not reuse a production client ID across independently operated hosted or native clients. A non-production lab may temporarily share one client app while testing callbacks, but use a distinct secret per vendor and do not copy that shape into customer production guidance.

Recommended split:

3. Record the non-secret values¶

Collect these values for CertifyClouds setup:

Do not record client secrets, access tokens, refresh tokens, authorization codes, secret values, or Key Vault material.

The Application ID URI is still used when clients request delegated scopes, for example https://<your-certifyclouds-host>/api/mcp/Mcp.Assets.Read. Do not assume that URI string is also the v2 token's aud value. Decode a short-lived test token locally, copy its exact aud claim into CertifyClouds, and then use the setup diagnostic to validate it.

CertifyClouds Setup¶

In CertifyClouds:

1. Open Settings -> MCP Connector.
2. Add a trusted issuer:
3. Issuer URL
4. JWKS URL
5. Tenant ID pin
6. Audience
7. Accepted client IDs

Every enabled issuer requires at least one accepted client ID. An empty list is rejected and never means "allow any client." 3. Add client policies for each accepted client ID. Use the Production client names above, then set allowed tools, maximum tenant scope, and whether Mcp.Audit.Read is permitted. 4. Map scopes to tool policies. Start with the recommended split above. 5. Restrict Mcp.Audit.Read to admin-equivalent users and approved clients. 6. Configure tenant scope policy: - home for the deployment tenant - tenant:<id> for named onboarded corporate tenants - all only where the user's CertifyClouds role and Entra scope justify it 7. Run the setup diagnostic: - JWKS reachability - Issuer and tenant pin check - Audience check - Accepted client ID check - Paste-a-token validation for signature, issuer, tenant, audience, expiry, token version, and accepted client ID, using a short-lived access token from a test user

Review the decoded scope claims against the configured scope-to-tool policies separately; the token diagnostic does not execute a tool authorization decision.

The diagnostic must not log or store the pasted token. Use it to verify claims and then discard the token.

Phase 1 does not support just-in-time user provisioning. The token's Entra oid must map to an existing, active CertifyClouds user or SSO account link. Create or link the CertifyClouds user before testing MCP access.

Enable or disable the connector¶

The deployment-level MCP switch defaults to off. Configure and save at least one enabled trusted issuer with an accepted client ID before the switch can be turned on.

1. Leave Enable MCP connector off while entering issuer, client, scope, and tenant policies.
2. Save the configuration and complete Test JWKS plus short-lived token validation.
3. Turn on Enable MCP connector and save again only after the diagnostics pass.
4. To withdraw the public MCP surface, turn the switch off and save. Remote clients can no longer discover or call the connector.

The saved configuration remains available to administrators while the connector is off, so it can be prepared or reviewed without admitting remote MCP traffic. Re-enabling does not require a restart.

Token diagnostic handling¶

Use a short-lived delegated Entra access token only for diagnostics. Acquire it through your organization's approved OAuth test tool or the current vendor setup flow, requesting the CertifyClouds MCP API (Production) delegated scopes. Keep it local to the administrator's workstation, paste it only into Settings -> MCP Connector, and never publish it in documentation, tickets, chat, shell history, screenshots, or logs.

CertifyClouds validates the pasted token as a resource server. It does not issue access tokens, authorization codes, or refresh tokens, and it does not host OAuth authorize or token endpoints.

Client Setup¶

Use the public MCP URL:

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

For an individual Claude account, open Customize -> Connectors, select + -> Add custom connector, and enter:

Click Add, then Connect, and complete the Entra sign-in. The authorization and token URLs come from Entra discovery, not from CertifyClouds. Each user authorizes with their own Entra identity and must already map to an active CertifyClouds user.

For Team and Enterprise plans, an Owner or Primary Owner first adds the Web connector under Organization settings -> Connectors -> Add -> Custom -> Web. Members then open Customize -> Connectors and select Connect. Claude's navigation and plan availability can change; use the current Claude connector guide linked above if the labels differ.

Optional ChatGPT web setup¶

ChatGPT is an optional additional client and is not part of the standard Claude Web setup. Use an eligible Pro, Plus, Business, Enterprise, or Education account and keep the app private until the full interoperability gate passes.

1. Open Settings -> Security and login and enable Developer mode.
2. Open Settings -> Plugins, select the plus button, and create a developer-mode app for https://<your-certifyclouds-host>/api/mcp using OAuth authentication.
3. Copy the exact callback URI that ChatGPT generates. Do not guess it or reuse the Claude callback URI.
4. Create a separate single-tenant confidential web client named CertifyClouds MCP Client - ChatGPT (Production) with that callback URI.
5. Create a client secret, grant only the required Phase 1 delegated scopes, and grant admin consent.
6. Return to ChatGPT, enter the client ID and secret, save the private app, and complete Entra authorization.
7. Open the app details and select Refresh to pull the current tools.
8. Confirm that exactly the eight Phase 1 read-only tools are discovered. Do not share or publish the app until tool calls, denials, audit attribution, refresh, and disconnect behavior have been verified.

ChatGPT requires refresh-token support for durable OAuth connectivity. Entra's OIDC discovery metadata must advertise offline_access, and the authorization flow must issue a refresh token.

Expected authorization server metadata:

https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

Expected protected-resource metadata:

https://<your-certifyclouds-host>/.well-known/oauth-protected-resource

Hosted ChatGPT custom app and Claude.ai custom connector flows were validated in lab on 2026-07-13. Both clients completed Entra connection and discovered the eight Phase 1 read-only tools; read-only hosted-client calls were also exercised. Keep the connector private until your own Entra, edge, denial, audit-attribution, refresh, and disconnect behavior have been verified for your deployment.

Final connector validation¶

After Entra, gateway, and Settings -> MCP Connector are configured:

1. Run Test JWKS and the short-lived token diagnostic. Confirm issuer, tenant, audience, client ID, signature, expiry, and token version all pass. Do not save or publish the token.
2. Connect the approved hosted client and complete Entra sign-in with an existing active CertifyClouds user.
3. Refresh the connector and confirm it discovers exactly the eight Phase 1 tools listed on this page, with no write or rotation-execution tool.
4. Ask the client to call cc_list_tenant_scopes, then make one scoped asset or compliance query.
5. Request a deliberately broader tenant scope and confirm it is denied cleanly.
6. In Audit Log, confirm the successful and denied MCP calls identify the mapped user, client, tool, and tenant scope without containing bearer tokens or secret values.

CertifyClouds operators use additional internal protocol and all-tool acceptance checks before declaring a release ready. Customers do not need repository scripts or direct database access to complete connector setup.

Troubleshooting¶

Security Notes¶

• Tokens are validated on every request. MCP-Session-Id is continuity only and is never trusted as identity.
• Issuer and tenant are pinned. CertifyClouds must not accept "any Entra tenant with the right audience".
• Access tokens are not forwarded to Azure, Graph, Key Vault, or third-party systems.
• Secret values, key material, and value-shaped hints are never returned by MCP tools.
• Read-only result metadata is returned to the customer-selected hosted AI provider when a user invokes a tool. Review that provider's retention, training, residency, and access controls before enabling the connector.
• All successful and denied tool calls are auditable in CertifyClouds.
• Revocation is controlled in Entra by disabling the user, removing app consent, removing scopes or roles, or disabling the client app. CertifyClouds can also deny a client or tool policy even when an Entra token is otherwise valid.

Phase 1 is deliberately read-only. Write tools and rotation workflows require a separate design, approval model, and release.