Object Storage MCP Server¶

Module: inception_mcp_servers/mcp_os/
Endpoint: http://127.0.0.1:3002/mcp/
Health: http://127.0.0.1:3002/health
Venv: .venv_mcp_os

Exposes Oracle Cloud Infrastructure Object Storage operations as MCP tools. Agents can upload, list, and delete objects in OCI buckets using their IDCS identity — no static OCI credentials required.

Exposed Tools¶

Controlled by TOOL_REGISTRY in registry.py:

Tool	Parameters	Description
`get_os_namespace`	`region: str`	Returns the OCI Object Storage namespace for the tenancy
`upload_object_file`	`region, bucket_name, object_name, file_name`	Uploads a local file to a bucket
`upload_object_remote`	`region, bucket_name, object_name, object_content`	Uploads text content directly to a bucket
`list_objects`	`region, bucket_name`	Lists all objects in a bucket
`delete_object`	`region, bucket_name, object_name`	Deletes an object from a bucket
`whoami`	—	Returns authenticated user info from token claims
`get_token`	—	Returns the current OAuth bearer token and JWT claims
`get_access_token_claims`	—	Extracts key JWT claims: `sub`, `uid`, `aud`, `iss`, `jti`

Exposed Resources¶

Controlled by RESOURCE_REGISTRY in registry.py:

Resource URI	Description
`oci://namespace`	OCI Object Storage namespace for the tenancy
`oci://buckets/{bucket_name}/objects`	Objects within a named bucket

Architecture¶

MCP Client
  │
  ▼ HTTP POST /mcp/
┌─────────────────────────┐
│      server_oidc.py     │  ← Interactive: OCIProvider (browser OAuth)
│   or server_token.py    │  ← Non-interactive: OCITokenAuthMiddleware (JWT bearer)
└──────────┬──────────────┘
           │ routes to registered tool or resource
           ▼
┌─────────────────────────┐
│       registry.py       │  ← TOOL_REGISTRY + RESOURCE_REGISTRY
└──────────┬──────────────┘
           │ calls
           ▼
┌─────────────────────────┐
│        tools.py         │
│  TokenExchangeSigner    │  ← converts IDCS token → OCI IAM signer
│  cache by jti claim     │
└──────────┬──────────────┘
           │ signed OCI API requests
           ▼
┌─────────────────────────┐
│   OCI Object Storage    │
│   API (REST)            │
└─────────────────────────┘

OCI Token Exchange¶

The Object Storage API requires requests signed with OCI credentials. This server converts the caller's IDCS JWT bearer token into an OCI TokenExchangeSigner via the OCI IAM token exchange endpoint.

IDCS Bearer Token
  → OCI IAM Token Exchange (grant: urn:ietf:params:oauth:grant-type:token-exchange)
  → OCI TokenExchangeSigner
  → Signs OCI Object Storage API request

Signer caching: ociclients.py caches signers in-memory, keyed by the token's jti claim. A new exchange only happens when a new (or rotated) token is presented. Cache is process-scoped.

Authentication¶

Interactive mode (`server_oidc.py`)¶

Provider: fastmcp.server.auth.providers.oci.OCIProvider
Client connects with auth="oauth" — FastMCP opens a browser for OCI IAM login
After login, tool calls are authorized by the issued access token
Required env vars: IDCS_DOMAIN, IDCS_CLIENT_ID, IDCS_CLIENT_SECRET

Bearer token mode (`server_token.py`)¶

Middleware: OCITokenAuthMiddleware + TokenVerifier
Client supplies Authorization: Bearer <token> on every request
Token validated via IDCS JWKS: https://{IDCS_DOMAIN}/admin/v1/SigningCert/jwk
Issuer: https://identity.oraclecloud.com/
Audience: https://{IDCS_DOMAIN}:443
Algorithm: RS256
Required env vars: IDCS_DOMAIN, MCP_ACCESS_TOKEN

Configuration¶

# .env
MCP_HOST_MCP_OS=127.0.0.1
MCP_PORT_MCP_OS=3002

# OCI IAM
IDCS_DOMAIN=<domain>.identity.oraclecloud.com    # bare hostname only
IDCS_CLIENT_ID=<client-id>
IDCS_CLIENT_SECRET=<client-secret>

# Token mode only
MCP_ACCESS_TOKEN=<oauth-access-token>

Running the Server¶

cd inception_mcp_servers/mcp_os

# First-time setup
.venv_mcp_os/bin/python -m pip install -r requirements.txt

# Interactive OIDC server
.venv_mcp_os/bin/python -m src.server_oidc

# Non-interactive bearer token server
.venv_mcp_os/bin/python -m src.server_token

Free the port if needed:

lsof -ti tcp:3002 | xargs kill -9

Testing¶

Bootstrap a token (run against `server_oidc.py`)¶

# server_oidc.py must be running
python -m tests.get_token
# Opens OCI browser login → writes MCP_ACCESS_TOKEN to .env

Non-interactive regression test (run against `server_token.py`)¶

python -m tests.test_mcp_os --url http://127.0.0.1:3002/mcp/ --region us-phoenix-1
# Optional: --access-token <token>

MCP Inspector¶

fastmcp dev --server-spec src/server_oidc.py:mcp   # interactive
fastmcp dev --server-spec src/server_token.py:mcp  # bearer token

Tool Response Format¶

All tools return structured JSON. Example for list_objects:

{
  "success": true,
  "objects": [
    {"name": "reports/q1.csv", "size": 4096, "time_created": "2026-04-01T00:00:00Z"},
    {"name": "reports/q2.csv", "size": 3821, "time_created": "2026-04-10T00:00:00Z"}
  ],
  "count": 2
}

On error:

{
  "success": false,
  "error": "<error message>"
}