# Ontology MCP

> Server URL, OAuth authorization, discovery, and errors for the read-only Ontology MCP server

The Ontology MCP is a read-only Model Context Protocol (MCP) server for the
Datastruct Ontology. Every request needs an OAuth 2.0 access token issued to
one of the signed-in user's personal OAuth credentials.

## Server

| Property | Value |
| --- | --- |
| Server URL | `https://console.datastruct.co/ontology/mcp` |
| Transport | MCP Streamable HTTP, `GET` and `POST` |
| Sessions | Stateless; send the access token with every request |
| Server name | `Datastruct Ontology` |
| Access | Read-only |

The URL is also accepted with a trailing slash. Use the URL without a
trailing slash in client configuration because it matches the token
audience.

The server returns usage instructions when the client initializes. See
[Ontology MCP tools](/docs/api/ontology-mcp/tools/) for the tool contract.

## Credentials

Create a credential in Datastruct Console under **My account** →
**OAuth credentials** → **Connect an AI assistant**. Open **My account** by
selecting your name at the bottom of the sidebar. The **OAuth credentials**
tab appears when the Ontology is available to your organization.

| Field | Required | Description |
| --- | --- | --- |
| Name | Yes | Your label for the credential |
| Client | Yes | The MCP client you will connect |
| Redirect URL | Conditional | The client's OAuth callback URL |
| Expiration | Yes | 7, 30, 60, or 90 days, a custom date, or none |

The default expiration is 30 days. A custom date can be up to one year away.
A credential stops working at the end of its last day in your Console time
zone.

Console lists supported clients with their callback URLs already registered.
For any other MCP client, select `Other` and enter its redirect URL. The
redirect URL must be an absolute `https` URL without a fragment or spaces.
Plain `http` is rejected, including for `localhost`. The authorization request
must use the same URL exactly.

The client secret is shown once, after the credential is created or its
secret is rotated. Datastruct does not store it.

## Connect an MCP client

Console shows these steps, tailored to the selected client, when you create a
credential. Menu names vary by client.

1. In Console, open **My account** → **OAuth credentials** and select
   **Connect an AI assistant**.
2. Enter a name, select the client, and choose an expiration. For `Other`,
   enter the client's redirect URL.
3. Select **Create credential**, then copy the client ID and client secret.
4. In your MCP client, add a custom connector or remote MCP server.
5. Enter the server URL, `https://console.datastruct.co/ontology/mcp`.
6. Choose OAuth authentication, then enter the client ID and client secret.
7. Connect. When the Datastruct page opens, sign in to Console if needed and
   select **Authorize**.

The client can then call the Ontology MCP tools. Selecting **Cancel** on the
Datastruct page denies access.

## Credential lifecycle

| Action | Effect |
| --- | --- |
| Rotate secret | Issues a new secret; the old secret and its tokens stop |
| Revoke | Deletes the credential; its tokens stop on the next request |
| Delete | Removes an expired credential from the list |

Only the credential owner can rotate its secret. The owner, and an
organization admin who manages credentials, can revoke or delete it.

## Authorization

The Ontology MCP uses the OAuth 2.0 authorization code grant with Proof Key
for Code Exchange (PKCE).

| Parameter | Value |
| --- | --- |
| Client type | Confidential |
| PKCE method | `S256` |
| Required scope | `ontology:read` |
| Refresh scope | `offline_access` |
| Access token lifetime | 60 minutes |
| Token audience | The server URL |
| Token use | `Authorization: Bearer <access-token>` header only |

During authorization, the user signs in to Datastruct Console and selects
**Authorize** on the approval page. Only the credential's owner can approve
it, and only while the credential is unexpired and the Ontology is available
to the owner's organization. The authorization response includes the `iss`
parameter.

Send the access token on every MCP request:

```http
POST /ontology/mcp HTTP/1.1
Host: console.datastruct.co
Authorization: Bearer <access-token>
Content-Type: application/json
Accept: application/json, text/event-stream
```

## Discovery

Clients discover the authorization server through OAuth 2.0 Protected
Resource Metadata (RFC 9728).

```http
GET /.well-known/oauth-protected-resource/ontology/mcp HTTP/1.1
Host: console.datastruct.co
```

`GET /.well-known/oauth-protected-resource` returns the same document.

Example response, with the issuer shown as a placeholder:

```json
{
  "resource": "https://console.datastruct.co/ontology/mcp",
  "authorization_servers": ["<authorization-server-issuer>"],
  "scopes_supported": ["ontology:read"],
  "bearer_methods_supported": ["header"]
}
```

| Field | Description |
| --- | --- |
| `resource` | The server URL and expected token audience |
| `authorization_servers` | The issuer that hosts authorization metadata |
| `scopes_supported` | The scope an access token must carry |
| `bearer_methods_supported` | Accepted token location |

Read the issuer from this document instead of configuring it. Fetch the
authorization server's own metadata from the issuer for its authorization and
token endpoints.

## Token acceptance

The server accepts an access token only when all of these conditions hold:

- The token is current and was issued by the Datastruct authorization server.
- Its audience includes the server URL.
- It carries the `ontology:read` scope.
- It belongs to an active Console user.
- It was issued to one of that user's own unexpired credentials.
- It was issued after the credential's latest secret rotation.
- The Ontology is available to the user's organization.

A token issued to another user's credential is rejected, including a
credential in the same organization.

## Errors

HTTP errors return a JSON body with a `detail` message.

| Status | Condition | `WWW-Authenticate` error |
| --- | --- | --- |
| `401` | No bearer token | None |
| `401` | Token invalid, expired, revoked, or for another resource | `invalid_token` |
| `403` | Token lacks `ontology:read` | `insufficient_scope` |
| `403` | The Ontology is shown to the organization but not enabled | None |
| `404` | The Ontology is unavailable to the organization | None |

Every `401` and `403 insufficient_scope` response includes a
`WWW-Authenticate` header that names the metadata URL:

```http
WWW-Authenticate: Bearer resource_metadata="https://console.datastruct.co/.well-known/oauth-protected-resource/ontology/mcp", error="invalid_token"
```

On `invalid_token`, obtain a new access token. If refresh fails, the
credential may be expired, revoked, or rotated; check it in Console. Tool-level
errors return a successful MCP response; see
[Ontology MCP tools](/docs/api/ontology-mcp/tools/#tool-errors).

## Related explanation

- [AI assistant access to the Ontology](/docs/topics/ontology-mcp/) explains
  personal credentials, consent, and revocation.