Oci Blueprint

Build, customize, package, and deploy a Python MCP server on Oracle Cloud Infrastructure.

This repository is a blueprint for teams that want to move from a local custom MCP server prototype to a cloud-ready service that can run on OCI Enterprise AI. The goal is to provide both a practical reference implementation and the supporting deployment infrastructure needed to adapt the server to real enterprise use cases.

The project currently includes:

• a Python MCP server skeleton with a clear project structure;
• two sample MCP tools that demonstrate the expected extension points;
• centralized runtime configuration for local and cloud execution;
• tests and specifications that document the intended behaviour;
• local development instructions for running and validating the server;
• a local Agent Factory for building, publishing, and deploying the server to OCI Enterprise AI Hosted Applications.

Project Scope

The blueprint focuses on a custom MCP server implemented in Python. It is meant to be adapted by replacing or extending the sample MCP capabilities while keeping the protocol boundary, configuration, packaging, and deployment flow easy to understand.

The repository is intentionally scoped to:

• MCP server implementation patterns;
• sample Python code for tools, resources, and prompts;
• local validation and automated tests;
• OCI-compatible packaging and deployment;
• a factory workflow for OCI Enterprise AI deployments.

It is not intended to become a collection of unrelated agents, clients, framework examples, or deployment targets.

Development Model

This project follows a spec-driven development workflow. Meaningful features, protocol changes, deployment changes, and behavioural changes should start with a specification under specs/ before implementation.

The first sample server design is documented in specs/001-sample-fastmcp-server.md. It defines a Python FastMCP server with two example tools, get_schema and get_data, backed by hard-coded fake database metadata and simulated rows.

The expected local Conda environment name is:

conda activate oci-mcp-blueprint

Install the package and development dependencies:

python -m pip install -e ".[dev]"

Optional local environment templates are documented in .env.example. Copy the values you need into an ignored .env file or export them in your shell before starting the local server, client, or deployment factory.

Run the sample MCP server:

python -m oci_mcp_blueprint.server

The server runs with FastMCP Streamable HTTP only. It binds to 0.0.0.0:8080 and serves the MCP endpoint at /mcp by default.

For local-only binding:

MCP_SERVER_HOST=127.0.0.1 python -m oci_mcp_blueprint.server

The same entry point is available as a console script:

oci-mcp-blueprint-server

Test a local or remote MCP endpoint with the command-line client:

oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp list-tools
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp get-schema
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp get-data "status == shipped"

For a protected remote deployment:

oci-mcp-blueprint-client \
  --url https://example-hosted-app.example.com/mcp \
  --bearer-token "$MCP_CLIENT_BEARER_TOKEN" \
  list-tools

Run the project checks:

python -m black --check .
python -m pylint src tests
python -m pytest

Run the Docker Compose deployment:

./start_server.sh
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp list-tools
./stop_server.sh

OCI Hosted Deployment Factory

The OCI Hosted Deployment Factory is a local web application that helps you deploy this blueprint's MCP server to OCI Enterprise AI Hosted Applications.

It is not part of the deployed MCP runtime. Instead, it is an operator tool that runs on your workstation or jump host and guides the deployment workflow:

• collects OCI, OCIR, Hosted Application, and MCP runtime settings;
• validates inputs and OCIR credentials;
• builds the repository root Dockerfile as the MCP server image;
• pushes the image to OCI Container Registry;
• creates or reuses the OCI Enterprise AI Hosted Application;
• creates a Hosted Deployment from the pushed image;
• validates the hosted MCP endpoint with the standard MCP list_tools operation;
• returns the hosted MCP Streamable HTTP URL.

The factory itself has two local services:

• agent-factory/api: FastAPI backend for deployment orchestration.
• agent-factory/ui: Next.js UI for guided input and progress tracking.

The deployed runtime remains the Python FastMCP server from src/oci_mcp_blueprint; it exposes Streamable HTTP at /mcp and does not include the factory UI or API.

Start the factory locally:

./start_factory.sh --build

Then open the factory UI at:

http://localhost:3100

The factory builds the root MCP server image, pushes it to OCIR, creates an OCI Enterprise AI Hosted Application deployment, validates the hosted MCP endpoint with list_tools, and returns the hosted /mcp URL. See docs/oci-hosted-deployment-factory.md for details.

Sample Tools

The server is intentionally a sample server. The schema and rows are fake, hard-coded, deterministic data used only to demonstrate how to build a modular MCP server.

get_schema

Returns a structured description of the fake order-management database schema. It supports:

• table_name: optional table filter;
• include_sample_rows: optional flag to include fake rows in the schema response.

get_data

Returns simulated rows from the fake database. It accepts:

• condition: required demo filter expression;
• table_name: optional table name, default orders;
• limit: optional row limit, default 10.

The condition is not SQL and is never executed against a database. Supported forms are:

field == value
field != value
field contains value

Example conditions:

status == shipped
customer_name contains acme
total_amount != 0

Project Layout

src/oci_mcp_blueprint/
  client.py
  config.py
  server.py
  domain/
    fake_database.py
    schema_service.py
    data_service.py
  mcp/
    models.py
    tools.py
tests/unit/
specs/
agent-factory/

Domain logic is separated from FastMCP registration so that another MCP server can be created by replacing the domain package and adapting the tool layer.

Runtime transport selection is intentionally not exposed. This blueprint supports only Streamable HTTP because it targets OCI Enterprise AI hosted deployment.

Documentation

• docs/customizing-mcp-server.md: file-by-file guide for replacing the sample domain and creating a custom MCP server.
• docs/docker-compose-deployment.md: local Docker Compose deployment and validation guide.

Security Notes

Do not commit secrets, private keys, API keys, OCI OCIDs, private endpoints, or environment-specific identifiers. Runtime configuration should use environment variables, ignored local configuration files, or documented placeholders.

The committed .env.example file contains only safe local defaults and empty placeholders. Keep real tokens, passwords, OCIDs, and environment-specific URLs in an ignored .env file or an external secret store.

Current Status

The repository contains the first sample FastMCP implementation and a local Docker Compose deployment. The next major step is the OCI Enterprise AI deployment factory.