Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 60 additions & 17 deletions src/oracle-db-mcp-java-toolkit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,46 @@ To enable YAML configuration, launch the server with:
java -DconfigFile=/path/to/config.yaml -jar <mcp-server>.jar
```

### Runtime configuration in a separate YAML file

Keep `configFile` for `dataSources`, custom `tools`, and `toolsets`. Put deployment settings that
would otherwise be JVM system properties in a separate runtime file selected with
`-DruntimeConfigFile`:

```yaml
network:
transport: "http"
http:
allowedOriginalHosts: "mcp.example.com"
https:
port: "45451"
certificatePath: "/run/secrets/server.p12"
certificatePassword: "${CERTIFICATE_PASSWORD}"
database:
url: "jdbc:oracle:thin:@//db.example.com:1521/ORCLPDB1"
user: "${DB_USER}"
password: "${DB_PASSWORD}"
userAuth:
enabled: "true"
```

Start with both files when custom tools or datasource definitions are needed:

```bash
java \
-DruntimeConfigFile=/path/to/runtime-config.yaml \
-DconfigFile=/path/to/config.yaml \
-jar <mcp-server>.jar
```

`runtimeConfigFile` and `configFile` are bootstrap properties and remain on the command line. A
non-blank `-D` property overrides the matching YAML value. Use the same canonical names in both
places: for example, `database.url` and `network.https.port`. Existing property names such as
`db.url` and `https.port` remain supported as compatibility aliases. When both forms are supplied,
the canonical property wins. Runtime YAML is resolved by the toolkit and is not written into JVM
system properties. See [`runtime-config.example.yaml`](runtime-config.example.yaml) for all
supported runtime settings.

Toolsets can be enabled from `-Dtools` alongside individual tools. For example:
- `-Dtools=reporting` enables all tools in the `reporting` toolset
- `-Dtools=reporting,explain` enables your `reporting` set plus the built-in `explain` toolset (see below)
Expand Down Expand Up @@ -469,7 +509,7 @@ _Note: The `mcp-admin` toolset is focused on protected runtime configuration and
- Requirements and behavior:
- Must be explicitly enabled with `-Dtools=list-credentials` or `-Dtools=mcp-admin`.
- When HTTP authentication is enabled, requires OAuth scope `mcp:credentials:read` or `mcp:admin`.
- To allow any authenticated caller to use `list-credentials` without scope enforcement, set `-DlistCredentials.requireScope=false`.
- Set `toolAuthorization.listCredentials.requireScope: false` only when every authenticated caller should be allowed to list credential metadata.

- `edit-tools`: Create, update, or remove a YAML-defined tool. Changes are auto-reloaded by the server.
- Inputs (subset; see schema in code):
Expand All @@ -484,7 +524,7 @@ _Note: The `mcp-admin` toolset is focused on protected runtime configuration and
- Must be explicitly enabled with `-Dtools=edit-tools` or `-Dtools=mcp-admin`.
- Requires `-DconfigFile` to be set to a writable YAML file; otherwise the tool will return an error.
- When HTTP authentication is enabled, requires OAuth scope `mcp:tools:write` or `mcp:admin`.
- To allow any authenticated caller to use `edit-tools` without scope enforcement, set `-DeditTools.requireScope=false`.
- Set `toolAuthorization.editTools.requireScope: false` only when every authenticated caller should be allowed to edit tools.
- OAuth scope lookup defaults to the `scope` claim in the introspection response. If your authorization server uses a different claim, configure its dot-separated path with `-Doauth.scopeClaimPath=<claim.path>`.
- Tool names must be safe and cannot collide with built-in tools or toolsets.
- For `edit-tools` changes, `dataSource` is required, must exist under `dataSources:`, and must be in `admin.editTools.allowedDataSources` when that allowlist is configured.
Expand Down Expand Up @@ -590,7 +630,7 @@ For local development only, an unauthenticated server can be started with `-Dhtt
-Dhttp.allowedOriginalHosts=mcp.example.com
```

Use a reverse proxy or firewall appropriate for your deployment. `allowedHosts` is a separate CORS setting for OAuth discovery metadata; it does not control MCP request admission.
Use a reverse proxy or firewall appropriate for your deployment. `network.cors.allowedOrigin` is a separate CORS setting for OAuth discovery metadata; it does not control MCP request admission. The legacy `allowedHosts` name remains supported.

##### Enabling HTTPS (SSL/TLS)

Expand Down Expand Up @@ -680,7 +720,7 @@ In order to configure an OAuth2 server, enable `-Dauth.enabled=true` alongside t
* `-Dauth.userTokenValidation.jwt.jwksCacheSeconds`: Optional JWKS cache duration in seconds when `auth.userTokenValidation.mode=jwt` (default: `600`).
* `-Dauth.userTokenValidation.introspection.clientId`: Client ID used for introspection (e.g. `oracle-db-toolkit`).
* `-Dauth.userTokenValidation.introspection.clientSecret`: Client secret used for introspection.
* `-DallowedHosts`: (default: `*`) The value of `Access-Control-Allow-Origin` header when requesting the `/.well-known/oauth-protected-resource` endpoint (and `/.well-known/oauth-authorization-server` if `-Dauth.openIdDiscoveryRedirectEnabled=true`) of the MCP Server.
* `-Dnetwork.cors.allowedOrigin`: (default: `*`) The value of the `Access-Control-Allow-Origin` header for the `/.well-known/oauth-protected-resource` endpoint (and `/.well-known/oauth-authorization-server` when enabled). The legacy `-DallowedHosts` alias remains supported.

##### MCP login scopes vs DeepSec database scopes

Expand All @@ -707,7 +747,7 @@ java \
-Dauth.userTokenValidation.introspection.endpoint=http://localhost:8080/realms/mcp/protocol/openid-connect/token/introspect \
-Dauth.userTokenValidation.introspection.clientId=oracle-db-toolkit \
-Dauth.userTokenValidation.introspection.clientSecret=Xj9mPqR2vL5kN8tY3hB7wF4uD6cA1eZ0 \
-DallowedHosts=http://localhost:6274 \
-Dnetwork.cors.allowedOrigin=http://localhost:6274 \
-jar <path-to-jar>/oracle-db-mcp-toolkit-1.0.0.jar
```

Expand Down Expand Up @@ -756,8 +796,6 @@ Required properties:
* `-Ddeepsec.databaseToken.clientId`: Client ID used to obtain the database-scoped DeepSec token.
* `-Ddeepsec.databaseToken.clientSecret`: Client secret used to obtain the database-scoped DeepSec token.
* `-Ddeepsec.databaseToken.scope`: Database resource scope for the DeepSec/database token, for example `OracleDBDB_ACCESS_SCOPE`.
* `-Doracle.ucp.createConnectionInBorrowThread=true`: Ensures UCP creates a new physical connection in the request thread that is borrowing it, so the current DeepSec context is available during connection creation.

Optional properties:

* `-Ddeepsec.databaseToken.staticValue`: Static database-scoped token for local smoke tests. Prefer `deepsec.databaseToken.tokenEndpoint` plus client credentials for normal use.
Expand Down Expand Up @@ -795,7 +833,6 @@ java \
-Ddb.url='jdbc:oracle:thin:@mydb_high?TNS_ADMIN=/path/to/wallet' \
-Ddb.user=mcp_app_user \
-Ddb.password='your-db-password' \
-Doracle.ucp.createConnectionInBorrowThread=true \
-Dtransport=http \
-Dhttps.port=8080 \
-DcertificatePath=/path/to/your-certificate.p12 \
Expand Down Expand Up @@ -1018,6 +1055,12 @@ Ultimately, the token must be included in the http request header (e.g. `Authori
<td>Path to a YAML file defining <code>datasources</code> and <code>tools</code>. Required if you intend to use the <code>edit-tools</code> admin tool to persist changes.</td>
<td>/opt/mcp/config.yaml</td>
</tr>
<tr>
<td><code>runtimeConfigFile</code></td>
<td>No</td>
<td>Path to a separate YAML file containing nested runtime settings. Individual JVM properties override its values.</td>
<td>/opt/mcp/runtime-config.yaml</td>
</tr>
<tr>
<td><code>auth.enabled</code></td>
<td>No</td>
Expand Down Expand Up @@ -1056,22 +1099,22 @@ Ultimately, the token must be included in the http request header (e.g. `Authori
<td><code>-Doauth.scopeClaimPath=scope</code></td>
</tr>
<tr>
<td><code>editTools.requireScope</code></td>
<td><code>toolAuthorization.editTools.requireScope</code></td>
<td>No</td>
<td>Whether <code>edit-tools</code> requires OAuth scope <code>mcp:tools:write</code> or <code>mcp:admin</code> when HTTP authentication is enabled. Defaults to <code>true</code>. Set to <code>false</code> only when any authenticated caller should be allowed to use <code>edit-tools</code>.</td>
<td><code>-DeditTools.requireScope=false</code></td>
<td>Whether <code>edit-tools</code> requires OAuth scope <code>mcp:tools:write</code> or <code>mcp:admin</code> when HTTP authentication is enabled. Defaults to <code>true</code>. Set to <code>false</code> only when any authenticated caller should be allowed to edit tools. The legacy <code>editTools.requireScope</code> name remains supported.</td>
<td><code>-DtoolAuthorization.editTools.requireScope=false</code></td>
</tr>
<tr>
<td><code>listCredentials.requireScope</code></td>
<td><code>toolAuthorization.listCredentials.requireScope</code></td>
<td>No</td>
<td>Whether <code>list-credentials</code> requires OAuth scope <code>mcp:credentials:read</code> or <code>mcp:admin</code> when HTTP authentication is enabled. Defaults to <code>true</code>. Set to <code>false</code> only when any authenticated caller should be allowed to list credential metadata.</td>
<td><code>-DlistCredentials.requireScope=false</code></td>
<td>Whether <code>list-credentials</code> requires OAuth scope <code>mcp:credentials:read</code> or <code>mcp:admin</code> when HTTP authentication is enabled. Defaults to <code>true</code>. Set to <code>false</code> only when any authenticated caller should be allowed to list credential metadata. The legacy <code>listCredentials.requireScope</code> name remains supported.</td>
<td><code>-DtoolAuthorization.listCredentials.requireScope=false</code></td>
</tr>
<tr>
<td><code>allowedHosts</code></td>
<td><code>network.cors.allowedOrigin</code></td>
<td>No</td>
<td>The <code>Access-Control-Allow-Origin</code> header value when making a request to the MCP Server's <code>/.well-known/oauth-protected-resource</code> endpoint (default <code>*</code> e.g. all hosts are allowed).</td>
<td><code>-DallowedHosts=http://localhost:6274</code></td>
<td>The <code>Access-Control-Allow-Origin</code> header value for OAuth discovery endpoints (default <code>*</code>). The legacy <code>allowedHosts</code> name remains supported.</td>
<td><code>-Dnetwork.cors.allowedOrigin=http://localhost:6274</code></td>
</tr>
<tr>
<td><code>auth.openIdDiscoveryRedirectEnabled</code></td>
Expand Down
66 changes: 66 additions & 0 deletions src/oracle-db-mcp-java-toolkit/runtime-config.example.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Start with: java -DruntimeConfigFile=/path/to/runtime-config.yaml -jar oracle-db-mcp-toolkit.jar
# Any non-blank -D property overrides the matching YAML setting below.
# Keep this deployment-specific file out of source control and provide secrets through environment variables.
network:
transport: "http"
http:
# Set this explicitly for production HTTP deployments.
allowedOriginalHosts: "mcp.example.com"
cors:
allowedOrigin: "*"
https:
port: "45451"
certificatePath: "/path/to/certificate.p12"
certificatePassword: "${CERTIFICATE_PASSWORD}"

toolSelection:
enabled: "read-query,write-query"
dataIngestion:
rootDirectory: "/data/ingest"
maxFileSizeMb: "100"
database:
url: "jdbc:oracle:thin:@tcps://db.example.com:1521/ORCLPDB1"
user: "${DB_USER}"
password: "${DB_PASSWORD}"
transactions:
idleTimeoutSeconds: "120"
maxLifetimeSeconds: "300"
maxPerUser: "4"
jdbc:
extensionsDirectory: "/opt/oracle/extensions"

userAuth:
openIdDiscoveryRedirectEnabled: "false"
enabled: "true"
authorizationServer: "https://identity.example.com/tenant-id"
tokenValidation:
mode: "jwt"
introspection:
endpoint: "https://identity.example.com/introspect"
clientId: "${INTROSPECTION_CLIENT_ID}"
clientSecret: "${INTROSPECTION_CLIENT_SECRET}"
jwt:
issuer: "https://identity.example.com/tenant-id/"
jwksUri: "https://identity.example.com/tenant-id/discovery/keys"
audience: "api://mcp-server"
jwksCacheSeconds: "600"

toolAuthorization:
editTools:
requireScope: "true"
listCredentials:
requireScope: "true"
mcp:
oauth:
scopes: "openid"
resourceUrl: "https://mcp.example.com/mcp"

deepDataSecurity:
enabled: "false"
# Set staticValue instead of the endpoint/client credentials when a database token is supplied directly.
databaseToken:
staticValue: "${DEEPSEC_DATABASE_TOKEN}"
tokenEndpoint: "https://identity.example.com/tenant-id/oauth2/v2.0/token"
clientId: "${DATABASE_TOKEN_CLIENT_ID}"
clientSecret: "${DATABASE_TOKEN_CLIENT_SECRET}"
scope: "api://database/.default"
Loading
Loading