health_checkLABSCO SUMMARY
Two separate switches: one for writes, one for destroying things.
Enabling record creation does not enable purges, which is exactly the split you want when an agent is doing bulk data work. The data domain is the setting that catches people out — it is the internal ACL domain rather than the hostname in your server URL, and entitlements_mine shows the format your own groups use.
What it is
A Python server over OSDU's services: search, storage, schema, legal, partition and entitlements. Writes are disabled by default and deletes are controlled separately, so a fresh install is read-only.
What you get
- Platform connectivity and service health — health_check
- Search with Elasticsearch syntax, by record id, or by kind — search_query, search_by_id, search_by_kind
- Records read by id or version, versions listed, ids queried by kind, and many records fetched at once — storage_get_record, storage_get_record_version, storage_list_record_versions, storage_query_records_by_kind, storage_fetch_records
- Records created or updated, logically deleted, and permanently purged — storage_create_update_records, storage_delete_record, storage_purge_record
- Schemas listed, fetched, searched with rich filtering, created and updated — schema_list, schema_get, schema_search, schema_create, schema_update
- Legal tags listed, fetched, searched, batch-retrieved, created, updated and deleted — legaltag_list, legaltag_get, legaltag_get_properties, legaltag_search, legaltag_batch_retrieve, legaltag_create, legaltag_update, legaltag_delete
- Partitions listed, read, created, updated and deleted, and the current user's groups — partition_list, partition_get, partition_create, partition_update, partition_delete, entitlements_mine
- Two prompts — list_mcp_assets for a capability overview, guide_search_patterns for Elasticsearch syntax
Requirements
OSDU_MCP_SERVER_URL and OSDU_MCP_SERVER_DATA_PARTITION, plus credentials — Azure (AZURE_CLIENT_ID and AZURE_TENANT_ID with az login, or a service principal secret), AWS or GCP are detected automatically, and OSDU_MCP_USER_TOKEN takes priority over all of them. Set OSDU_MCP_SERVER_DOMAIN to your deployment's data domain or ACL formats will be wrong. Writes need OSDU_MCP_ENABLE_WRITE_MODE and deletes need OSDU_MCP_ENABLE_DELETE_MODE. Runs with uvx straight from the repository.
Setup effort
One command plus credentials — claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" -e "OSDU_MCP_SERVER_URL=<YOUR_OSDU_MCP_SERVER_URL>" -e "OSDU_MCP_SERVER_DATA_PARTITION=<YOUR_OSDU_MCP_SERVER_DATA_PARTITION>" -e "AZURE_CLIENT_ID=<YOUR_AZURE_CLIENT_ID>" -e "AZURE_TENANT_ID=<YOUR_AZURE_TENANT_ID>", then supply credentials
USE CASES
01
Finding records without knowing the schema
Search by kind or with Elasticsearch syntax, and read the bundled search-pattern prompt when the query language is unfamiliar.
02
Reading a record's history
List every version of a record and fetch a specific one, rather than only seeing the current state.
03
Getting ACLs right the first time
Read your own entitlement groups to see the exact domain format your deployment uses, before writing a record that will be rejected.
04
Loading data with a safety margin
Turn on write mode and leave delete mode off, so an agent can create and update but cannot logically delete or purge anything.
31 tools
Listed in project docs. Your client may show a different list.
partition_listpartition_getpartition_createpartition_updatepartition_deleteentitlements_minelegaltag_listlegaltag_getlegaltag_get_propertieslegaltag_searchlegaltag_batch_retrievelegaltag_createlegaltag_updatelegaltag_deleteschema_listschema_getschema_searchschema_createschema_updatesearch_querysearch_by_idsearch_by_kindstorage_create_update_recordsstorage_get_recordstorage_get_record_versionstorage_list_record_versionsstorage_query_records_by_kindstorage_fetch_recordsstorage_delete_recordstorage_purge_recordBEFORE YOU INSTALL
What to know first
Tools you get
31 tools named in the project's documentation. Eleven write tools, including partition_create, legaltag_delete, storage_delete_record and storage_purge_record, are listed but return 403 until OSDU_MCP_ENABLE_WRITE_MODE=true and the delete flags are set.
Requires
- uvx on PATH
- OSDU_MCP_SERVER_URL in your environment
- OSDU_MCP_SERVER_DATA_PARTITION in your environment
- Credentials for one provider: Azure (AZURE_CLIENT_ID and AZURE_TENANT_ID after az login, or a service principal secret), AWS (a profile or IAM credentials), GCP (a service-account file in GOOGLE_APPLICATION_CREDENTIALS), or a user token in OSDU_MCP_USER_TOKEN
INSTALLATION
Connect your client
Server setup
Setup
To run it from a local checkout instead of uvx:
TERMINAL
git clone https://github.com/danielscholl-osdu/osdu-mcp-server.git
cd osdu-mcp-server
uv sync
uv pip install -e '.[dev]'Then point the client at the checkout with command uv, args ["run", "osdu-mcp-server"]
Azure CLI auth additionally requires az login first, plus authorizing the client ID under your OSDU app registration (Expose an API -> Authorized client applications -> user_impersonation)
AWS SSO auth additionally requires aws sso login --profile dev-profile first; GCP CLI auth requires gcloud auth application-default login first
claude mcp add
TERMINAL
claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
-e "OSDU_MCP_SERVER_URL=<YOUR_OSDU_MCP_SERVER_URL>" \
-e "OSDU_MCP_SERVER_DATA_PARTITION=<YOUR_OSDU_MCP_SERVER_DATA_PARTITION>" \
-e "AZURE_CLIENT_ID=<YOUR_AZURE_CLIENT_ID>" \
-e "AZURE_TENANT_ID=<YOUR_AZURE_TENANT_ID>"MCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" -e "OSDU_MCP_SERVER_URL=<YOUR_OSDU_MCP_SERVER_URL>" -e "OSDU_MCP_SERVER_DATA_PARTITION=<YOUR_OSDU_MCP_SERVER_DATA_PARTITION>" -e "AZURE_CLIENT_ID=<YOUR_AZURE_CLIENT_ID>" -e "AZURE_TENANT_ID=<YOUR_AZURE_TENANT_ID>"Any MCP client — uvx
ANY MCP CLIENT — UVX · JSON
{
"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": "<YOUR_OSDU_MCP_SERVER_URL>",
"OSDU_MCP_SERVER_DATA_PARTITION": "<YOUR_OSDU_MCP_SERVER_DATA_PARTITION>",
"AZURE_CLIENT_ID": "<YOUR_AZURE_CLIENT_ID>",
"AZURE_TENANT_ID": "<YOUR_AZURE_TENANT_ID>"
}
}
}
}The configuration on this page does not set OSDU_MCP_USER_TOKEN, AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, AZURE_CLIENT_SECRET, AWS_SECRET_ACCESS_KEY and AWS_PROFILE; the project's instructions set them with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply them, use the block's "env" section.
VS Code
Add this to .vscode/mcp.json. VS Code asks for the OSDU URL, data partition and Azure IDs the first time the server starts.
VS CODE · JSON
{
"inputs": [
{
"id": "osdu_url",
"type": "promptString",
"description": "OSDU Server URL (e.g., <YOUR_OSDU_MCP_SERVER_URL>)"
},
{
"id": "data_partition",
"type": "promptString",
"description": "OSDU Data Partition (e.g., <YOUR_OSDU_MCP_SERVER_DATA_PARTITION>)"
},
{
"id": "azure_client_id",
"type": "promptString",
"description": "Azure Client ID"
},
{
"id": "azure_tenant_id",
"type": "promptString",
"description": "Azure Tenant ID"
},
{
"id": "azure_client_secret",
"type": "promptString",
"description": "Azure Client Secret (optional for Service Principal auth)",
"password": true
}
],
"servers": {
"osdu-mcp-server": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/danielscholl-osdu/osdu-mcp-server@main",
"osdu-mcp-server"
],
"env": {
"OSDU_MCP_SERVER_URL": "${input:osdu_url}",
"OSDU_MCP_SERVER_DATA_PARTITION": "${input:data_partition}",
"AZURE_CLIENT_ID": "${input:azure_client_id}",
"AZURE_TENANT_ID": "${input:azure_tenant_id}"
}
}
}
}The configuration on this page does not set OSDU_MCP_USER_TOKEN, AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, AZURE_CLIENT_SECRET, AWS_SECRET_ACCESS_KEY and AWS_PROFILE; the project's instructions set them with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply them, use the block's "env" section.
Any MCP client — local build
ANY MCP CLIENT — LOCAL BUILD · JSON
{
"mcpServers": {
"osdu-mcp-server": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"osdu-mcp-server"
],
"env": {
"OSDU_MCP_SERVER_URL": "<YOUR_OSDU_MCP_SERVER_URL>",
"OSDU_MCP_SERVER_DATA_PARTITION": "<YOUR_OSDU_MCP_SERVER_DATA_PARTITION>",
"AZURE_CLIENT_ID": "<YOUR_AZURE_CLIENT_ID>",
"AZURE_TENANT_ID": "<YOUR_AZURE_TENANT_ID>"
}
}
}
}The configuration on this page does not set OSDU_MCP_USER_TOKEN, AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, AZURE_CLIENT_SECRET, AWS_SECRET_ACCESS_KEY and AWS_PROFILE; the project's instructions set them with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply them, use the block's "env" section.
