Skip to main content

​
Overview

Cursor is an AI-first code editor built on VS Code that natively supports the Model Context Protocol. By connecting Cursor to Oracle MCP Servers, you can leverage OCI services directly within your development workflow.

​
Prerequisites

Before configuring Cursor, ensure you have completed:

​
Configuration Locations

Cursor supports two configuration scopes:

​
Project Configuration

For tools specific to a project, create .cursor/mcp.json in your project directory. This makes MCP servers available only within that specific project. Use case: Project-specific OCI resources, development compartments, or testing environments.

​
Global Configuration

For tools you want across all projects, create ~/.cursor/mcp.json in your home directory. This makes MCP servers available in all Cursor workspaces. Use case: Commonly used OCI services, shared infrastructure, or organization-wide resources.

​
Configuration

​
Standard Configuration (stdio)

Create or edit your mcp.json file (either .cursor/mcp.json for project-level or ~/.cursor/mcp.json for global).

​
macOS/Linux

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "<profile_name>",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}
Replace <profile_name> with the OCI CLI profile you set up during authentication.

​
Windows

Windows configuration follows the same pattern as macOS/Linux. The main difference is path formatting and environment variable syntax. Refer to the Installation guide for Windows-specific examples.

​
Podman Configuration

To run Oracle MCP Servers in containers using podman: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "podman",
      "args": [
        "run", "-i", "--rm", 
        "-v", "/path/to/your/.oci:/app/.oci", 
        "oracle.oci-api-mcp-server:latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
Important Notes:
  • Replace "/path/to/your/.oci" with the actual path to your OCI configuration directory
  • For servers not requiring OCI credentials, omit the -v volume mount
  • Ensure proper file paths in your OCI config use the ~ character for container compatibility

​
HTTP Streaming Configuration

If you’re running an MCP server as a standalone HTTP service:
  1. Start the server:
ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 uvx oracle.oci-api-mcp-server
  1. Configure Cursor:
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "http",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}
Cursor uses http as the transport type for HTTP streaming, unlike some other clients that use streamableHttp.

​
Setup Steps

1

Create Configuration File

Create your mcp.json file in the appropriate location:
  • Project: .cursor/mcp.json in your project root
  • Global: ~/.cursor/mcp.json in your home directory
2

Add Server Configuration

Add your desired Oracle MCP Server configuration(s) to the file using the examples above.
3

Save Configuration

Save the mcp.json file. Cursor will automatically detect and load the configuration.
4

Verify Installation

Open Cursor Settings and navigate to the MCP tab to check Installed Servers.

​
Verification

​
Check Installed Servers

  1. Open Cursor Settings (Cmd+, on macOS or Ctrl+, on Windows/Linux)
  2. Navigate to the MCP tab
  3. Check the Installed Servers section
  4. Verify your Oracle MCP Servers appear in the list

​
Test the Connection

Try using Cursor’s AI features to interact with OCI:
  • Ask Cursor to list your OCI compartments
  • Request information about compute instances
  • Query OCI resources in your tenancy

​
Configuration Priority

When both project and global configurations exist:
  1. Project configuration (.cursor/mcp.json) takes precedence for that project
  2. Global configuration (~/.cursor/mcp.json) applies to all other projects
  3. Servers with the same name in project config override global config

​
Example: Mixed Configuration

Global (~/.cursor/mcp.json): 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["oracle.oci-api-mcp-server"],
      "env": {
        "OCI_CONFIG_PROFILE": "DEFAULT"
      }
    }
  }
}
Project (.cursor/mcp.json): 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["oracle.oci-api-mcp-server"],
      "env": {
        "OCI_CONFIG_PROFILE": "PROJECT_SPECIFIC"
      }
    },
    "oracle-dbtools-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["oracle.dbtools-mcp-server"]
    }
  }
}
In this setup, the project uses the PROJECT_SPECIFIC OCI profile and has access to both API and DBTools servers.

​
Troubleshooting

​
Server Not Appearing in Settings

  • Verify the JSON syntax is valid (use a JSON validator)
  • Ensure the file is named exactly mcp.json
  • Check file permissions (must be readable by Cursor)
  • Restart Cursor after creating/modifying the configuration

​
Connection Failures

  • Verify uv is installed and accessible in your PATH
  • Check that the OCI profile exists: cat ~/.oci/config
  • Ensure OCI authentication is properly configured
  • Review server logs by setting FASTMCP_LOG_LEVEL to DEBUG

​
Authentication Errors

  • Verify the OCI profile name matches your configuration
  • Check if your OCI session token has expired
  • Refresh authentication: oci session authenticate --profile-name <profile_name>

​
Multiple Servers

You can configure multiple Oracle MCP Servers in the same configuration file: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["oracle.oci-api-mcp-server"],
      "env": {
        "OCI_CONFIG_PROFILE": "DEFAULT",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    },
    "oracle-dbtools-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["oracle.dbtools-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

​
Next Steps

Explore Available Servers

Discover all Oracle MCP Servers you can connect to

Authentication Guide

Learn more about OCI authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us