3 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 disabled. 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.

See Also:

Using ORDS Model Context Protocol (MCP)

3.1 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 used for ORDS REST APIs with ORDS_PUBLIC_USER that is used to proxy to REST enabled schemas. This means that the user you select for your MCP database pool will be the user used to execute all MCP Tool requests.

Parent topic: Configuring Model Context Protocol (MCP)

3.2 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.

Parent topic: Configuring Model Context Protocol (MCP)

3.3 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, then the /mcp endpoint is disabled and requests to /mcp are not served.

Parent topic: Configuring Model Context Protocol (MCP)

3.4 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.

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 not configured, ORDS MCP uses scope mode for pool authorization. If it is configured, then ORDS MCP uses role mode.

Parent topic: Configuring Model Context Protocol (MCP)

3.5 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

Parent topic: Configuring Model Context Protocol (MCP)

3.6 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 scope claim provides the required scope for MCP "urn:oracle:dbtools:ords:mcpserver:all"

  • 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 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

Parent topic: Configuring Model Context Protocol (MCP)

3.7 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.

Parent topic: Configuring Model Context Protocol (MCP)

3.8 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 correct 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.

Parent topic: Configuring Model Context Protocol (MCP)