Configuring Model Context Protocol (MCP)

This chapter explains how to enable the /mcp endpoint, configure JWT validation for authentication, and specify the ORDS database pools that are accessible through MCP.

Oracle REST Data Services (ORDS) can provide a Model Context Protocol (MCP) server that enables authenticated AI clients and developer tools to access database resources. By default, ORDS MCP is not enabled. After it is enabled, ORDS uses a global MCP JWT profile for authentication and provides the MCP Client access to the database connections.

The ORDS MCP runtime is supported only in ORDS standalone deployments. When ORDS is deployed on Tomcat or WebLogic, the /mcp endpoints are not available.

About ORDS Model Context Protocol Configuration

ORDS MCP is available at the /mcp endpoint on the ORDS host. It is not served under the /ords REST-enabled schema path.

When an MCP client first accesses /mcp, ORDS MCP returns 401 Unauthorized with a WWW-Authenticate challenge pointing to the well-known metadata endpoint, which the client uses to discover where to obtain a JWT access token and continue the OAuth 2.0 flow. ORDS validates the bearer token using the global MCP JWT Profile, including the configured issuer, audience, and JWK-backed signature validation. After the token is accepted, ORDS exposes only the MCP-enabled database connection pools that the caller is authorized to access, based on the token’s configured scopes or roles.

In MCP client responses, ORDS uses the term database for a configured MCP target. In ORDS configuration, each MCP database is backed by a direct database pool with pool credentials.

Only direct database pools are eligible for ORDS MCP. A database pool configured with mcp.scope or mcp.role is reserved exclusively for MCP and is not used for REST URL mapping.

Direct connection pools are defined by the actual user to be used for the connection. This contrasts with proxy connection pools that you may use for ORDS REST APIs with ORDS_PUBLIC_USER that proxies to REST-enabled schemas. The user you select for your MCP database pool executes all MCP tool requests.

ORDS MCP Configuration Settings

ORDS MCP uses global settings to control endpoint availability and JWT validation:

feature.mcp: Enables or disables the /mcp endpoint. The default value is false.
mcp.security.jwt.profile.issuer: Specifies the expected JWT issuer.
mcp.security.jwt.profile.audience: Specifies the expected JWT audience, typically the /mcp resource URI.
mcp.security.jwt.profile.jwk.url: Specifies the JSON Web Key Set (JWKS) URL used to validate JWT signatures.
mcp.security.jwt.profile.authorization.server.url: Optionally specifies the authorization server URL to include in OAuth protected resource metadata.
mcp.security.jwt.profile.role.claim.name: Optionally specifies the JSON Pointer to the JWT role claim. When this setting is configured, ORDS MCP uses role mode for authorization. If it is not configured, ORDS MCP uses scope mode.

ORDS MCP uses the following pool-specific settings to expose a direct database pool through MCP:

mcp.scope: Specifies the scope required to access the database pool when ORDS MCP operates in scope mode.
mcp.role: Specifies the role required to access the database pool when ORDS MCP operates in role mode.
db.description: Optionally specifies the database pool description returned by the database_list operation when the client requests detailed information.

The following setting controls whether database schemas can provide custom reports through ORDS MCP:

feature.mcp.schemaReports: Enables custom reports stored in the DBTOOLS$MCP_REPORTS table for the selected MCP database pool. The default value is false.

Enable the ORDS MCP Endpoint

Enable the ORDS MCP endpoint by setting the global feature.mcp configuration property:

ords --config /path/to/conf config set --global feature.mcp true

If feature.mcp is false or not set, ORDS does not serve requests to the /mcp endpoint.

Configure the Global MCP JWT Profile

To configure the JWT profile that ORDS uses to validate MCP bearer tokens, run the following ORDS CLI commands:

ords --config /path/to/conf config set --global mcp.security.jwt.profile.issuer https://idp.example.com
ords --config /path/to/conf config set --global mcp.security.jwt.profile.audience https://ords.example.com/mcp
ords --config /path/to/conf config set --global mcp.security.jwt.profile.jwk.url https://idp.example.com/.well-known/jwks.json
ords --config /path/to/conf config set --global mcp.security.jwt.profile.authorization.server.url https://idp.example.com

The authorization server URL is optional. When configured, ORDS includes it in the OAuth protected-resource metadata for the /mcp endpoint, enabling MCP clients to automatically discover the authorization server. If the authorization server URL is not configured, then ORDS MCP continues to function as long as the issuer, audience, and JWK URL settings are configured. In this case, ORDS omits the authorization_servers field from the protected-resource metadata. This enables administrators to keep the authorization server private, but requires MCP clients to be configured with the authorization server explicitly, since it cannot be discovered automatically from ORDS.

If mcp.security.jwt.profile.role.claim.name is not configured, ORDS MCP uses scope mode for pool authorization. The caller token must contain the global MCP access scope urn:oracle:dbtools:ords:mcpserver:all.

If mcp.security.jwt.profile.role.claim.name is configured, ORDS MCP uses role mode for pool authorization. The caller token must contain the global MCP access role ORDS_MCP_SERVER.

Configure MCP Databases in Scope Mode

In scope mode, each MCP database pool must specify the scope required to access the pool.

Run the following ORDS CLI commands to expose the mcp-hr database pool through MCP with the global MCP access scope configured as the pool scope:

ords --config /path/to/conf config --db-pool mcp-hr set mcp.scope urn:oracle:dbtools:ords:mcpserver:all
ords --config /path/to/conf config --db-pool mcp-hr set db.description "HR reporting database"

Run the following ORDS CLI command to require a custom pool scope:

ords --config /path/to/conf config --db-pool finance set mcp.scope urn:example:ords:mcp:finance

For a custom pool scope, the caller token must contain both the global MCP access scope and the custom pool scope.

Example JWT Payload

{
  "iss": "https://idp.example.com",
  "sub": "auth0|6a3d7f722913da150ac58f3c",
  "aud": "https://ords.example.com/mcp",
  "iat": 1782493244,
  "exp": 1782579644,
  "scope": "urn:oracle:dbtools:ords:mcpserver:all",
  "azp": "tpc_5J8M7hyRHBriMaf9Zo68w9"
}

Note:

The JWT iss claim matches the ORDS global setting mcp.security.jwt.profile.issuer
The JWT aud claim matches the ORDS global setting mcp.security.jwt.profile.audience
The scope claim includes the scope required for MCP access urn:oracle:dbtools:ords:mcpserver:all.
The scope claim also includes the value configured for the database connection pool’s mcp.scope setting. In this example, the required value is also urn:oracle:dbtools:ords:mcpserver:all.
The JWT iat, exp and signature must all be valid

Configure MCP Databases in Role Mode

In role mode, configure the JWT claim that contains roles, then assign a required role to each MCP database pool.

Run the following ORDS CLI commands to read the roles from the JWT /roles claim and expose the mcp-hr database pool only to callers with the ORDS_MCP_HR role:

ords --config /path/to/conf config set --global mcp.security.jwt.profile.role.claim.name /roles2
ords --config /path/to/conf config --db-pool mcp-hr set mcp.role ORDS_MCP_HR

In role mode, only database pools configured with mcp.role are exposed through MCP.

Example JWT Payload

{
  "iss": "https://idp.example.com",
  "sub": "auth0|6a3d7f722913da150ac58f3c",
  "aud": "https://ords.example.com/mcp",
  "iat": 1782493244,
  "exp": 1782579644,
  "scope": "urn:oracle:dbtools:ords:mcpserver:all",
  "roles2": [
    "ORDS_MCP_HR"
  ],
  "azp": "tpc_5J8M7hyRHBriMaf9Zo68w9"
}

Note:

The JWT iss claim matches the ORDS global setting mcp.security.jwt.profile.issuer
The JWT aud claim matches the ORDS global setting mcp.security.jwt.profile.audience
The roles2 claim is matched with the global setting mcp.security.jwt.profile.role.claim.name. The JWT roles2 claim must provide a role that:
- provides the required role for MCP ORDS_MCP_SERVER
- matches the mcp.role pool setting to access that database connection pool. In this example, the required role is ORDS_MCP_HR.
The JWT iat, exp and signature must all be valid.

Configure Schema-Based Reports

Use the ORDS CLI to enable feature.mcp.schemaReports for an MCP database pool:

ords --config /path/to/conf config --db-pool sales set feature.mcp.schemaReports true

See Also:

Custom Report Tools in the Oracle REST Data Services Developer’s Guide
About the Oracle REST Data Services Configuration Files in this guide

Verify MCP Configuration

Start or restart ORDS after updating the configuration.

Run the following command to confirm that /mcp is protected:

curl -i https://ords.example.com/mcp

When ORDS MCP is enabled and the global JWT profile is fully configured, ORDS returns a Bearer authentication challenge. The challenge includes a resource metadata reference that MCP clients use for authorization discovery.

Run the following command to verify the protected-resource metadata:

curl -i https://ords.example.com/.well-known/oauth-protected-resource/mcp

If the global MCP JWT profile is incomplete, ORDS does not enable access to the /mcp endpoint.

Troubleshoot MCP Configuration

If the /mcp endpoint is not available, verify that feature.mcp is set to true in the global configuration.

If the /mcp endpoint returns an authentication or service error, verify that the global MCP JWT profile is fully configured with the expected issuer, audience, and JWK URL. Also verify that the identity provider is accessible and can serve the configured JWK URL.

If the MCP client authenticates successfully but no databases are returned, verify the following:

The caller token contains the global MCP access scope
In scope mode, the target database pool is configured with mcp.scope, and the caller token contains the required scope.
In role mode, mcp.security.jwt.profile.role.claim.name is configured with the expected JWT role claim, the target database pool is configured with mcp.role, and the token contains the required role.
The target database pool is a direct database pool configured with pool credentials.

If a database pool is no longer accessible through the standard ORDS REST URL mapping after MCP configuration, verify whether mcp.scope or mcp.role was intentionally configured for that pool. Pools with those settings are reserved for MCP.