OSDU MCP Server

Access OSDU platform capabilities including search, data management, and schema operations.

A Model Context Protocol (MCP) server that provides AI assistants with access to OSDU platform capabilities.

This server enables AI assistants to interact with OSDU platform services including search, data management, and schema operations through the MCP protocol.

This project follows an AI-driven development workflow:

- 🤖Built with AI- Developed using Claude Code and GitHub Copilot
- 📋AI Task Assignment- Issues labeled withcopilotare automatically assigned
- 📚AI-Friendly Documentation- Comprehensive guides for AI agents inCLAUDE.mdand.github/copilot-instructions.md
- 🔄Multi-Agent Orchestration- Different AI agents handle different tasks based on their strengths

See ourCase Studyfor insights on building quality code with AI agents.

- Project Brief
- Project Requirements
- Architecture Overview
- Architecture Design Decisions

# Clone the repository git clone <repository-url> cd osdu-mcp-server # Install using uv (recommended) uv sync uv pip install -e '.[dev]'

To add this MCP server using the Claude Code CLI:

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "AZURE_CLIENT_ID=your-client-id" \ -e "AZURE_TENANT_ID=your-tenant-id"

To use this MCP server in your projects, add the following to your.mcp.jsonfile:

{ "mcpServers": { "osdu-mcp-server": { "type": "stdio", "command": "uvx", "args": [ "--from", "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main", "osdu-mcp-server" ], "env": { "OSDU_MCP_SERVER_URL": "https://your-osdu.com", "OSDU_MCP_SERVER_DATA_PARTITION": "your-partition", "AZURE_CLIENT_ID": "your-client-id", "AZURE_TENANT_ID": "your-tenant-id" } } } }

For local development, you can also use the local installation method:

To use the OSDU MCP Server, configure it through your MCP client's configuration file:

{ "mcpServers": { "osdu-mcp-server": { "type": "stdio", "command": "uv", "args": ["run", "osdu-mcp-server"], "env": { "OSDU_MCP_SERVER_URL": "https://your-osdu.com", "OSDU_MCP_SERVER_DATA_PARTITION": "your-partition", "AZURE_CLIENT_ID": "your-client-id", "AZURE_TENANT_ID": "your-tenant" } } } }

Critical for ACL Format: OSDU deployments use different data domain formats for Access Control Lists (ACL). Configure your data domain to avoid ACL format errors:

"env": { "OSDU_MCP_SERVER_DOMAIN": "contoso.com" }

- Standard OSDU:contoso.com(default)
- Microsoft OSDU:dataservices.energy
- Microsoft Internal:msft-osdu-test.org
- Environment Variable(Recommended): SetOSDU_MCP_SERVER_DOMAIN
- Use Entitlements Tool: Runentitlements_mine()to see your group format
- Check with Administrator: Ask your OSDU administrator for the correct data domain

Important: The data domain is the internal OSDU data system domain used in ACL group emails, not the FQDN from your server URL.

If not set, the server will attempt to extract the domain from your server URL. For more guidance, use the MCP resource:ReadMcpResourceTool(server="osdu-mcp-server", uri="file://acl-format-examples.json").

The server supportsmulti-cloud authenticationwith automatic provider detection:

The server automatically detects your authentication provider in this priority order:
- Manual Token(highest priority) -OSDU_MCP_USER_TOKEN
- Azure-AZURE_CLIENT_IDorAZURE_TENANT_ID
- AWS(explicit) -AWS_ACCESS_KEY_IDorAWS_PROFILE
- GCP(explicit) -GOOGLE_APPLICATION_CREDENTIALS
- AWS(auto-discovery) - IAM roles, SSO
- GCP(auto-discovery) - gcloud, metadata service

- Setup: Runaz loginbefore using the server
- Environment Variables:

- AZURE_CLIENT_ID: Your OSDU application ID
- AZURE_TENANT_ID: Your Azure tenant ID
- NoAZURE_CLIENT_SECRETneeded

az login claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "AZURE_CLIENT_ID=your-osdu-app-id" \ -e "AZURE_TENANT_ID=your-tenant-id"

Method 2: Service Principal (Production)

- Setup: Create or use an existing service principal
- Environment Variables:

- AZURE_CLIENT_ID: Service principal ID
- AZURE_CLIENT_SECRET: Service principal secret
- AZURE_TENANT_ID: Your Azure tenant ID
- OSDU_MCP_AUTH_SCOPE: (Optional) Custom OAuth scope for v1.0 token environments (see GCP Authentication for its GCP meaning)

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "AZURE_CLIENT_ID=your-service-principal-id" \ -e "AZURE_CLIENT_SECRET=your-service-principal-secret" \ -e "AZURE_TENANT_ID=your-tenant-id"

- Setup: Configure AWS SSO and log in
- Environment Variables:

- AWS_PROFILE: Your AWS profile name
- (Other OSDU config as usual)

aws sso login --profile dev-profile claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "AWS_PROFILE=dev-profile"

- Setup: Obtain AWS access keys
- Environment Variables:

- AWS_ACCESS_KEY_ID: Your AWS access key
- AWS_SECRET_ACCESS_KEY: Your AWS secret key
- AWS_REGION: AWS region (e.g., us-east-1)

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE" \ -e "AWS_SECRET_ACCESS_KEY=your-secret-key" \ -e "AWS_REGION=us-east-1"

- Setup: Assign IAM role to your compute instance
- Environment Variables: None needed! Automatic credential discovery
- Note: Works on EC2, ECS/Fargate, Lambda with appropriate IAM roles

- Setup: Rungcloud auth application-default login
- Environment Variables: None needed! Automatic credential discovery

gcloud auth application-default login claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition"

Method 2: Service Account Key (Production)

- Setup: Download service account JSON key
- Environment Variables:

- GOOGLE_APPLICATION_CREDENTIALS: Path to service account JSON key

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json"

- Setup: Configure Workload Identity on GKE
- Environment Variables: None needed! Automatic credential discovery
- Note: Works on GKE with Workload Identity configured

All GCP methods requestcloud-platformplus the identity scopesopenidanduserinfo.emailby default. The identity scopes grant no additional access — they make the caller's email address present in the token, which OSDU requires to resolve entitlements. Without them every OSDU request fails with401 Access denied.

- OSDU_MCP_AUTH_SCOPE: (Optional) Comma-separated list of scopes that replaces the defaults

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "OSDU_MCP_AUTH_SCOPE=https://www.googleapis.com/auth/cloud-platform,openid,https://www.googleapis.com/auth/userinfo.email"

Use Case: Custom OAuth providers, testing, or unsupported clouds

- Setup: Obtain OAuth Bearer token from your provider
- Environment Variables:

- OSDU_MCP_USER_TOKEN: Your OAuth Bearer token (JWT format)
- Priority: This method ALWAYS takes precedence over all others

# Obtain token from your OAuth provider TOKEN=$(your-oauth-command) claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \ -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \ -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \ -e "OSDU_MCP_USER_TOKEN=$TOKEN"

- Valid JWT format (header.payload.signature)
- Not expired
- Server warns if token expires within 5 minutes

- Tokens are validated for format and expiration
- Tokens are never logged
- Tokens must be refreshed manually when they expire

- ✅Azure CLI auth: Always requires authorization setup
- ✅External service principal: Requires authorization setup
- ❌OSDU app's own service principal: No additional setup needed

For Azure CLI or External Service Principal:
- Navigate to your OSDU applicationinApp registrations
- Go to Expose an API→Authorized client applications
- Click Add a client application
- Enter the client ID:

- Azure CLI:04b07795-8ddb-461a-bbee-02f9e1bf7b46
- External Service Principal: Your service principal's ID

az account get-access-token --resource YOUR_AZURE_CLIENT_ID

- "Application not found": Azure CLI app doesn't exist in some tenants. Use service principal instead.
- "Invalid resource": The client hasn't been authorized. Follow authorization setup above.
- "Authentication failed": Verify your client ID matches your OSDU application or service principal.

Write operations (create, update) for any service are disabled by default, you must explicitly enable them:

"env": { "OSDU_MCP_ENABLE_WRITE_MODE": "true" }

Delete and purge operations are separately controlled and disabled by default:

"env": { "OSDU_MCP_ENABLE_DELETE_MODE": "true" }

This dual protection allows you to enable data creation and updates while maintaining strict control over destructive operations.

Here's a complete.mcp.jsonconfiguration example with all common environment variables:

{ "mcpServers": { "osdu-mcp-server": { "type": "stdio", "command": "uv", "args": ["run", "osdu-mcp-server"], "env": { "OSDU_MCP_SERVER_URL": "https://your-osdu.com", "OSDU_MCP_SERVER_DATA_PARTITION": "opendes", "OSDU_MCP_SERVER_DOMAIN": "contoso.com", "OSDU_MCP_ENABLE_WRITE_MODE": "true", "OSDU_MCP_ENABLE_DELETE_MODE": "true", "AZURE_CLIENT_ID": "your-client-id", "AZURE_TENANT_ID": "your-tenant-id", "AZURE_CLIENT_SECRET": "your-client-secret" } } } }

The MCP server uses structured JSON logging that followsADR-016. By default, logging is disabled due to verbosity. You can enable it by setting:

"env": { "OSDU_MCP_LOGGING_ENABLED": "true", "OSDU_MCP_LOGGING_LEVEL": "INFO" }

A simple MCP server for Elasticsearch, designed for cloud environments where your public key is already authorized.