osdu

The OSDS MCP Server exposes OSDU platform capabilities to AI assistants via the MCP protocol, enabling interactions with OSDU services such as search, data management, and schema operations. It is designed to be integrated into your MCP client workflow so agents can query OSDU resources, manage data objects, and validate schemas through a standardized, model-context-aware interface. To begin, deploy the server using UV (via uvx) and supply the required environment variables for authentication and targeting the correct OSDU deployment. Once running, you can add the MCP server to your client configuration and begin issuing requests to perform actions like searching for data, uploading or updating records, and validating or retrieving schema definitions.

Typical usage involves configuring the MCP client to reference this server by name (osdu-mcp-server) and providing the connection details via environment variables. The server supports multiple authentication methods (manual token, Azure, AWS, GCP) and can infer provider context based on your environment, so ensure your chosen method is available in the environment before sending requests. Documentation within the repository also covers domain configuration needed for ACLs and how to specify the data domain for ACLs if you encounter access control errors.

Prerequisites:

• Python 3.12 or newer (per repository shields)
• Git
• UV tool (recommended): https://uv.sh/

1. Clone the repository:

git clone https://github.com/danielscholl-osdu/osdu-mcp-server.git
cd osdu-mcp-server

2. Install dependencies and set up the development environment using UV:

uv sync
uv pip install -e '.[dev]'

3. Run the MCP server integration using UVX (as in the configuration example):

# Ensure environment variables are set, for example in a .env file or your shell:
export OSDU_MCP_SERVER_URL="https://your-osdu.com"
export OSDU_MCP_SERVER_DATA_PARTITION="your-partition"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_TENANT_ID="your-tenant-id"
export OSDU_MCP_SERVER_DOMAIN="contoso.com"

# Start via UVX (as defined in mcp_config):
uvx --from git+https://github.com/danielscholl-osdu/osdu-mcp-server@main osdu-mcp-server

4. Alternative: add this MCP server to your local MCP config file as shown in README under Direct Installation:

{
  "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"
      }
    }
  }
}

Environment and configuration tips:

• Domain configuration is important for ACLs. Set OSDU_MCP_SERVER_DOMAIN to your data domain (e.g., contoso.com, dataservices.energy, or msft-osdu-test.org) to avoid ACL format errors.
• If your deployment requires a manual token, set OSDU_MCP_USER_TOKEN. The server supports multiple authentication methods with a priority order including manual tokens, Azure, AWS, and GCP.
• For development, you can also use the local development path shown in the README to run the server through the UV workflow or via a local MCP client configuration.
• When using the Claude Code CLI or VS Code Quick Install, provide the required environment variables (URL, data partition, and credentials) to ensure proper authentication and routing to your OSDU deployment.