MCP Server

DevHub ships a built-in Model Context Protocol (MCP) server that exposes your QueryDesk databases to external AI clients — Claude Desktop, Cursor, and any other MCP-capable app. The AI can list databases, read schema, and run governed queries, all under the same access controls, data protection, and audit trail as a human user.

The endpoint

The MCP server is mounted at:

https://your-org.devhub.cloud/mcp

It speaks MCP over streamable HTTP. Most clients only need this URL — they discover the authorization server and register themselves automatically (see below).

Identity model

An MCP session always acts as the user who authorized it. When you connect, you sign in through DevHub and consent to the connection; the AI then operates as your user. That means:

• It can only see and query databases you have access to.
• Every query is subject to your data-protection policy redaction.
• The AI's per-database caps and the peer-review approval gate apply exactly as they do to a person — see AI Governance.
• Every query the AI runs is attributed to you in the audit log and labeled as AI-originated.

The AI inherits your permissions and nothing more.

An agent that runs with nobody to sign in connects as a service account instead.

Authorizing a client (OAuth 2.1)

The MCP server is protected by an OAuth 2.1 authorization server built into DevHub. It supports the discovery and registration flow that modern MCP clients expect, so in practice you rarely configure any of this by hand.

Discovery

Clients locate the authorization server and its endpoints from two .well-known metadata documents.

Protected-resource metadata

curl https://your-org.devhub.cloud/.well-known/oauth-protected-resource

{
  "resource": "https://your-org.devhub.cloud/mcp",
  "authorization_servers": ["https://your-org.devhub.cloud"],
  "scopes_supported": ["mcp"],
  "bearer_methods_supported": ["header"]
}

Authorization-server metadata

curl https://your-org.devhub.cloud/.well-known/oauth-authorization-server

{
  "issuer": "https://your-org.devhub.cloud",
  "authorization_endpoint": "https://your-org.devhub.cloud/oauth/authorize",
  "token_endpoint": "https://your-org.devhub.cloud/oauth/token",
  "registration_endpoint": "https://your-org.devhub.cloud/oauth/register",
  "jwks_uri": "https://your-org.devhub.cloud/.well-known/jwks.json",
  "scopes_supported": ["mcp"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_basic",
    "client_secret_post"
  ]
}

Dynamic client registration

Clients register themselves with the authorization server using Dynamic Client Registration (RFC 7591) — you don't create an OAuth client by hand. The client POSTs its metadata and gets back a client_id (and a client_secret for confidential clients).

curl -X POST https://your-org.devhub.cloud/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Claude Desktop",
    "redirect_uris": ["https://client.example.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "mcp"
  }'

{
  "client_id": "oauth_client_abc123",
  "client_id_issued_at": 1718000000,
  "client_name": "Claude Desktop",
  "redirect_uris": ["https://client.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp"
}

Authorization code + PKCE

The client sends the user to /oauth/authorize with a PKCE challenge (only the S256 method is supported). The user signs in through the normal DevHub login — including your organization's IdP if you use SSO — and approves a consent screen showing the client and the access it's requesting. DevHub redirects back with an authorization code, which the client exchanges at /oauth/token for an access token (and a refresh token). Access tokens are short-lived; clients use the refresh token to stay connected.

Connect a client

Most MCP clients only need the endpoint URL — they run discovery, registration, and the OAuth flow for you. Point your client at https://your-org.devhub.cloud/mcp:

claude mcp add --transport http devhub https://your-org.devhub.cloud/mcp

The first time you connect, your browser opens to the DevHub consent screen; approve it and the client is connected. From there the AI can call the MCP tools — subject to the controls described in AI Governance.

Service accounts

A service account connects an unattended agent, such as a scheduled job or an incident bot, to the MCP server. It belongs to your organization, not to a person. It takes no seat and is not listed under Users. The agent sends a static bearer token on every request, with no sign-in, no consent screen and no refresh. Any number of agent instances can use the same token at once.

Only a super admin can create, edit, rotate or revoke service accounts, under Settings > Service accounts.

Create one

1. Open Settings > Service accounts and choose New service account.
2. Give it a name and, if you want the token to stop working on a date, an expiration.
3. Copy the token. DevHub shows it once and stores only a hash, so it cannot show it again.

A new service account can call no tools and reaches only databases that are open to all users. Open its row to turn on tools and give it databases.

Connect the agent

Send the token as a bearer token on every MCP request:

Authorization: Bearer dhsa_...

claude mcp add --transport http devhub https://your-org.devhub.cloud/mcp \
  --header "Authorization: Bearer dhsa_..."

Give it databases and tools

A service account gets databases the same two ways a member does.

• On a database's settings page, under RBAC, choose Add service account. The grant is always Run Queries, and you can assign it a data protection policy.
• Assign the service account a role, from the role's page or from the service account's drawer. It gets every database the role is granted Run Queries on. A role's Approver grant gives a service account nothing.

On a database it reaches, the agent can run as any credential you allowed for AI, while AI access is on for that database. If you turn AI access off, or no credential is AI-allowed any more, the drawer marks the grant Unreachable and the agent loses the database without anyone editing the service account.

In the drawer, turn on the tools the agent may call. Every tool starts off. The agent is offered only the tools that are on, and a call to any other tool is refused. A tool added to the MCP server later starts off and is marked New until you next change the selection.

Rotate the token

Choose Rotate token in the drawer to replace a lost or exposed token. The service account keeps its databases, tools and audit trail, and DevHub shows the new token once. The previous token stops working on the next MCP request, so update your agents with the new token right away. Rotating does not change the expiration.

Expiration and revocation

When a service account reaches its expiration, or you choose Revoke, the next MCP request with its token fails as unauthorized. Other service accounts and members' connected applications keep working. Revoking cannot be undone. The audit log keeps the service account's queries under its name.

Custom clients

If you're building your own client rather than using an off-the-shelf one, complete the OAuth 2.1 flow described above and send the resulting access token as a bearer token on every request:

Authorization: Bearer <access_token>