oci-mcp-server MCP Server: Comprehensive Integration for AI Applications

Overview: What is oci-mcp-server MCP Server?

oci-mcp-server is a specialized Python-based MCP (Model Context Protocol) server designed to streamline and standardize the interaction between AI applications such as Claude Desktop, Continue, Cursor, and others, with Oracle Cloud Infrastructure (OCI) API Gateway resources. This server serves as a bridge, enabling these applications to access and manage API Gateway tools through a standardized protocol, offering both programmatic and natural language interactions.

🔧 Core Features & MCP Capabilities

oci-mcp-server supports key features that encompass the core capabilities of the Model Context Protocol (MCP). These include:

• List API Gateways: The server allows listing all API gateways within a specified OCI compartment.
• Get Gateway Details: Retrieve detailed information about a specific gateway based on its ID.
• MCP stdio Transport: This transport mechanism facilitates seamless interactions with LLM agents and other clients, enabling easy integration into the development workflow.
• LlamaIndex/Ollama Client: Users can interact with OCI API Gateways using natural language queries, enhancing the usability of these tools.

⚙️ MCP Architecture & Protocol Implementation

The architecture of oci-mcp-server is designed to seamlessly integrate with MCP clients like Cursor and other AI applications. It leverages Python for its implementation, ensuring compatibility with a wide range of environments. The protocol flow diagram provides insight into how data moves between the AI application, the MCP client, and the server.

Mermaid Diagram: MCP Protocol Flow

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

Mermaid Diagram: Data Architecture

graph TD
    A[OCI Compartment] -->|API Gateways| B[MCP Server]
    B --> C[GATEWAY_ID_1]
    B --> D[GATEWAY_ID_2]
    style A fill:#e8f5e8
    style B fill:#f3e5f5
    style C fill:#dce4ff
    style D fill:#dce4ff

🚀 Getting Started with Installation

To set up and run the oci-mcp-server, you need to meet a few prerequisites:

1. Python 3.11
2. uv (fast Python package/dependency manager)
3. OCI account with API Gateway access
4. OCI session authentication files (~/.oci/sessions/DEFAULT/token and oci_api_key.pem)

Follow these steps to install the necessary components:

1. Install uv

curl -Ls https://astral.sh/uv/install.sh | sh

Alternatively, you can use pip:

pip install uv
# or with pipx
pipx install uv

You can also update uv if installed from the standalone installer:

uv self-update

More installation methods are available in the uv documentation.

2. Create and Activate a Virtual Environment

uv venv --python 3.11
source .venv/bin/activate

3. Install Dependencies

uv pip install -r pyproject.toml
# or with `uv`
uv pip install -e .

💡 Key Use Cases in AI Workflows

oci-mcp-server facilitates several AI workflows by providing a robust and flexible interface between the client applications and API Gateway resources. Two realistic use cases are:

1. Listing APIs for DevOps Team: A development team can use this server to list all APIs within their OCI tenancy, quickly identifying and managing API gateways.

2. Gateway Management for API Teams: An API management team can utilize natural language queries via the LlamaIndex/Ollama client to get detailed information about specific gateway configurations without writing complex code.

🔌 Integration with MCP Clients

Integration with MCP clients like Cursor is seamless, offering both programmatic and natural language interaction capabilities. Here are steps to integrate:

1. Install Cursor:

   • Download and install Cursor from the official website for your platform (macOS, Windows, Linux).
   • Follow the installation instructions specific to your OS.

2. Update mcp.json Configuration:

   • Open the Cursor settings by navigating to Cursor > Settings... > Cursor Settings.
   • Select MCP > + Add new global MCP server.
   • Copy the content of src/mcp_template.json to ~/.cursor/mcp.json or directly in the editor.
   • Replace placeholders with your actual paths and configurations.

3. Run the MCP Server:

python src/server.py

This will start the MCP server, exposing tools like list_gateways_tool and get_gateway_tool.

📊 Performance & Compatibility Matrix

OCI-mcp-server ensures compatibility across multiple MCP clients, providing a seamless experience for developers. The compatibility matrix includes support for popular AI applications:

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	✅	Full Support
Cursor	❌	✅	❌	Tools Only

🛠️ Advanced Configuration & Security

For advanced configuration and security, you can edit the src/config.py file to set your OCI compartment and gateway OCIDs, region, and profile as needed:

PROFILE_NAME = 'DEFAULT'
REGION = 'ap-mumbai-1'
SERVICE_ENDPOINT = '<SERVICE ENDPOINT>'
COMPARTMENT_ID = '<COMPARTMENT_ID>'
GATEWAY_ID = '<GATEWAY_ID>' # For Programmatic Client

Ensure you have valid OCI session files in ~/.oci/sessions/DEFAULT/.

You can authenticate your session using:

oci session authenticate --tenancy-name <TENANCY_NAME> --profile-name DEFAULT --region $REGION

❓ Frequently Asked Questions (FAQ)

1. How do I set up the server?

• Install uv and create a virtual environment.
• Run the server using Python from the project root.

2. Can I interact with the gateway using natural language?

• Yes, by configuring the LlamaIndex/Ollama client in Cursor.

3. What are the prerequisites for running this server?

• Python 3.11 and valid OCI session files are required.

4. How can I ensure compatibility with different MCP clients?

• The compatibility matrix can guide you to prepare your setup accordingly.

5. Are there any performance issues with this implementation?

• Given the streamlined architecture, performance is optimized for both local and remote interactions.

👨‍💻 Development & Contribution Guidelines

All source code resides in the src/ directory. Dependencies are managed via pyproject.toml. To add new tools, edit src/server.py and implement logic in src/gateway_services.py.

To contribute or report issues, please refer to the project repository's contributing guidelines.

🌐 MCP Ecosystem & Resources

The oci-mcp-server is part of a broader ecosystem focused on integrating AI applications with specific data sources using standardized protocols. Explore other resources such as:

• MCP Protocol Documentation
• Cursor SDK for MCP Integration

This comprehensive documentation serves as a valuable resource, providing detailed guidance on setting up and utilizing the oci-mcp-server with Oracle Cloud Infrastructure API Gateway tools.