Oracle Cloud Infrastructure Documentation

Tutorial: Set Up a Database Tools MCP Server and Integrate with an MCP Client

The objective of this tutorial is to create a Database Tools MCP server, secure it with identity domain and application roles, and integrate it with an MCP client such as the Cline extension for Visual Studio Code.

By the end, you will have:

  • An MCP server with a Database Tools connection.
  • A toolset (Built-in SQL tools).
  • Users or groups mapped to Application Roles.
  • An MCP client that connects to the server using a Personal Access Token or Token-based Authentication.

Steps for Creating a Database Tools MCP Server and Integrating with the Client

This table lists the steps to create a Database Tools MCP server and integrate it with the MCP client.

Step Task Process
1 Create a compartment named dbtools-mcp. Create a Compartment
2 Create an IAM domain named dbtools-mcp. Create an Identity Domain
3 Create an Autonomous AI Database named dbtoolsmcp in the dbtools-mcp compartment. Provision an Autonomous AI Database Instance
4 Create a vault and key in the dbtools-mcp compartment.

Creating a Vault

Create a Master Encryption Key
5 Create a database connection. Create a Database Connection
6 Create an MCP server. Create a Database Tools MCP Server
7 Configure IAM domain roles. Setup IAM Domain Roles
8 Create a policy named dbtools-mcp in the root compartment. Creating a Policy

For the MCP Server with Runtime Identity set to Resource Principal, use the following policy statements: 

allow group 'dbtools-mcp'/'MCP_All_Users' to use database-tools-mcp-servers-invocation in compartment dbtools-mcp
allow any-user to use database-tools-connections in compartment dbtools-mcp where request.principal.id = 'ocid1.databasetoolsmcpserver.oc1.phx.xxxx'
allow any-user to use database-tools-runtime-work-requests in compartment dbtools-mcp where request.principal.id = 'ocid1.databasetoolsmcpserver.oc1.phx.xxxx'
allow any-user to read secret-bundles in compartment dbtools-mcp where request.principal.id = 'ocid1.databasetoolsmcpserver.oc1.phx.xxxx'
allow any-user to use buckets in compartment dbtools-mcp where request.principal.id = 'ocid1.databasetoolsmcpserver.oc1.phx.xxxx'
allow any-user to manage objects in compartment dbtools-mcp where request.principal.id = 'ocid1.databasetoolsmcpserver.oc1.phx.xxxx'

For the MCP Server with Runtime Identity set to Authenticated Principal, use the following policy statements: 

allow group 'dbtools-mcp'/'MCP_All_Users' to use database-tools-mcp-servers-invocation in compartment dbtools-mcp
allow group 'dbtools-mcp'/'MCP_All_Users' to use database-connections in compartment dbtools-mcp
allow group 'dbtools-mcp'/'MCP_All_Users' to use database-tools-connections in compartment dbtools-mcp
allow group 'dbtools-mcp'/'MCP_All_Users' to use database-tools-runtime-work-requests in compartment dbtools-mcp
allow group 'dbtools-mcp'/'MCP_All_Users' to read secret-bundles in compartment dbtools-mcp
allow group 'dbtools-mcp'/'MCP_All_Users' to use buckets in compartment dbtools-mcp
allow group 'dbtools-mcp'/'MCP_All_Users' to manage objects in compartment dbtools-mcp

See Policies for MCP Server for more information.

9 For token-based authentication, create a policy to enable IAM authentication and create database users.

  1. Create a policy to enable MCP users to use IAM Authentication.

    allow group 'dbtools-mcp'/'MCP_All_Users' to use database-connections in compartment dbtools-mcp

  2. Create database users (global schemas) using the SQL Worksheet.

    -- Global schema with exclusive mapping 
CREATE USER scott IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=dbtools-mcp/scott@example.com';

-- Global schema with shared mapping 
CREATE USER mcp_users IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=dbtools-mcp/MCP_Users';
10 Create an MCP toolset. Create an MCP Toolset
11 Register an MCP client. Registering an MCP Client
12 Connect to the MCP server using a Personal Access Token or token-based authentication.

Connect to the MCP Server Using a Personal Access Token

Connect to the MCP Server Using Token-Based Authentication

Create a Database Connection

For Password-Based Authentication

  1. Create a Database Tools connection dbuser@dbtoolsmcp with the schema that will be used to connect to the database.

    For more information about creating a connection, see Creating a Connection.

  2. Enter the following details when creating the connection:

    • Select Oracle Autonomous AI Database.
    • Enter username: ADMIN.
    • Select user password secret.
    • Select Wallet format: Oracle auto-login wallet (for example, cwallet.sso)
    • Select SSO wallet content secret.
    • In Advanced options - Settings, set Runtime Identity to Resource Principal.
      Note

      • Connection resource principal is used to retrieve secrets.
      • The user password secret and wallet content secret must be created in the same compartment where the Database Tools connection resource principal is allowed to read secrets.

For Token-Based Authentication

  1. Create a Database Tools connection admin@dbtoolsmcp in the dbtools-mcp compartment with a privileged user (for example, ADMIN) using password-based authentication.
  2. Enable IAM Authentication in the database.
    1. Select the admin@dbtoolsmcp connection.
    2. Expand Actions and select Configure external authentication.
    3. For External authentication type, select OCI_IAM.
    4. Click Update to save the configuration.

  3. Create a Database Tools connection dbtoolsmcp in the dbtools-mcp compartment using token-based authetication.

    When creating the connection:

    • Select Oracle Autonomous AI Database.
    • In Advanced Options - Authentication, enable Use token based authentication.

Create a Database Tools MCP Server

  1. Open the navigation menu and select Developer Services.
  2. In the Database Tools section, select Model Context Protocol Servers.
  3. In the Model Context Protocol servers page, click Create Model Context Protocol server.
  4. Enter the following details:
    • Name: Enter mcpserver.
    • Domain: Select dbtools-mcp.
    • Connection:
      • For password-based authentication, select mcp@dbtoolsmcp.
      • For token-based authentication, select dbtoolsmcp.
    • Select Object Storage Bucket to enable asynchronous operations.
    • In Advanced options, for OAuth options, consider increasing the Access token expiration to 1 week (604800 seconds) if users must download a Personal Access Token to configure their MCP client.
  5. Click Create.

Setup IAM Domain Roles

This part includes the following steps:

  1. Create groups in the domain for each application role.
  2. Assign groups to application roles.
  3. Create users in the domain.
  4. Assign users to groups.

Create Groups in the Domain for Each Application Role

  1. In the Model Context Protocol Servers page, select mcpserver, and then Domain.

  2. In the dbtools-mcp domain, go to User management and then Groups.

  3. Create the following groups:

    Group Name Application Role
    MCP_Administrators MCP_Administrator
    MCP_Operators MCP_Operator
    MCP_Users MCP_User
    MCP_All_Users Not Applicable

    For more information about creating groups in domains, see Creating a Group.

Assign Groups to Application Roles

  1. In the Model Context Protocol Servers page, select mcpserver, and then select the Roles tab.
  2. Click Assign Roles.

  3. For each Application Role:

    1. Click the Actions icon and select Manage groups.
    2. Click Assign groups.
    3. Select the required groups in the list of Available groups.
    4. Click Assign.

Create Users in the Domain

For the domain dbtools-mcp, create users.

See Create a User in an Identity Domain to learn how to create a user in an identity domain.

Assign Users to Groups

For the dbtools-mcp domain, assign users to groups.

See Adding a User to a Group to learn how to add a user to a group.

Note

You must have an Application Role assigned to use the MCP server and to download Personal Access Tokens.

Create an MCP Toolset

  1. In the Model Context Protocol Servers page, click the name of the MCP server that was created.
  2. In the specific MCP server page, select the Toolsets tab.
  3. Click Create Model Context Protocol Toolset.

  4. Enter the following details for creating the toolset. The following example is an SQL query for a toolset that lists the employees that match a specific criteria.

    Note

    Ensure that the EMPLOYEES table already exists and includes the FIRST_NAME and LAST_NAME columns before creating the toolset.
    • Name: Enter a name for the toolset, such as List employees matching substring.
    • Description: Enter a description for the toolset such as List employees matching substring passed as parameter "substring".
    • Compartment: Select the compartment for the toolset.
    • Type: Select the type of toolset. In this example, select Custom SQL tool.
    • Tool name: Enter list_employees_matching_substring.
    • Tool description: Enter List employees matching substring passed as parameter "substring".
    • Allowed Roles: Select from the predefined application roles. See Application Roles for more information.
    • SQL source: Enter the following code for this example:
      SELECT * FROM EMPLOYEES
WHERE LAST_NAME LIKE'%'|| :substring ||'%'
OR FIRST_NAME LIKE'%'|| :substring ||'%'
    • Variables: Add Name substring, Type VARCHAR2, and Description "The substring to search for in first name and last name".
  5. Click Create.

Connect to the MCP Server Using a Personal Access Token

Generate a Personal Access Token

  1. Click the Profile icon and select <user email id>.

  2. Select the Tokens and keys tab.

  3. In the My access tokens section, for Invokes other APIs, click Download Token.

    This image shows the Tokens and Keys tab and where a user must click to download the token.

  4. In the Generate personal access token page:

    1. Select the MCP server for which you want to generate a token.
    2. In Token expires in mins, select the token expiry duration in minutes (For example, 10080 minutes is equivalent to one week).
      Note

      The Access Token Expiration setting for the MCP server is superseded by the duration that is specified for the MCP server Token Expires in mins setting. Go to the MCP server Details page to see the Access Token Expiration setting. See Connecting to an MCP Server to know where to find the Access Token Expiration setting.
    3. Click Download Token.

Configure the MCP Client to Connect to the MCP Server

  1. In the Cline extension for Visual Studio Code, select the MCP Servers icon, then select the Remote Servers tab.
  2. Enter a name for the server and the Server URL. The Server URL is available on the MCP server's Details page as follows: 
    https://example.oraclecloud.com/../actions/invoke
  3. In Transport Type, select Streamable HTTP.

  4. Click Add Server.

    This image shows the Server Name and Server URL fields in the Cline extension.

    The Configure tab is selected and the server is displayed with an error.

    This image shows the Configure MCP Servers option.

  5. Click Configure MCP Servers.

    The contents of the cline_mcp_setting json file are displayed in the right pane.

    Update the file as follows:

    {
  "mcpServers": {
    "dbtools-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://mcp.../x.xxxxx/actions/invoke",
      "headers": {
        "Authorization": "Bearer {Add downloaded token}"
      }
    }
  }
}

  6. Save the file.

    The error message is resolved. This is indicated by a green indicator that appears in the same row as the server name.

    This image shows the green indicator that appears at the end of the row.

    Expand the server name to see the available Tools, Resources and Prompts.

    This image shows the screen where the available tools, resources and prompts are displayed.

Connect to the MCP Server Using Token-Based Authentication

To connect the Cline extension for VS Code to your MCP server using mcp-remote with a registered Public Client, you need to configure the server within VS Code and then complete the authentication flow through a browser prompt.

  1. Install mcp-remote.

    Use the following command :

    npm install -g mcp-remote

  2. Edit the cline_mcp_settings.json file: 

    {
  "mcpServers": {
    "dbtools-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.…./actions/invoke",
        "8080",
        "--transport",
        "http-only",
        "--static-oauth-client-metadata",
        "{ \"scope\": \"https://mcp." }",
        "--static-oauth-client-info",
        "{ \"client_id\": \"xxxx\" }"
      ]
    }
  }
}

    Ensure your OAuth Public Client is configured with this redirect URI: http://localhost:8080/oauth/callback.

    Note

    The port (8080) must match the port number you pass to mcp-remote in the JSON configuration file.

    After you sign in, mcp-remote stores tokens locally on your machine.

    Example: 

    ~/.mcp-auth/mcp-remote-N.N.NN/xxxxx_tokens.json

  3. Restart VS Code, then connect to dbtools-mcp-server in Cline. Your browser opens to complete the sign-in and approve access.