OData MCP Bridge (Go)

★ 138

from oisee

A Go bridge providing universal access to OData v2 services through MCP tools, with support for multiple authentication methods.

🔥🔥🔥🔥✓ VerifiedPaid serviceAdvanced setup

#automation #devops #git #maps #security

OData MCP Bridge (Go)

A Go implementation of the OData to Model Context Protocol (MCP) bridge, providing universal access to OData services through MCP tools.

This is a Go port of the Python OData-MCP bridge implementation, designed to be easier to run on different operating systems with better performance and simpler deployment. It supports both OData v2 and v4 services.

🆕 What's New (v1.6.0)

Universal Tool Mode — One Tool to Rule Them All

The biggest addition is Universal Tool Mode (--universal), a game-changer for large OData services:

Copy & paste — that's it

# Before: 485 tools, ~37,000 tokens, Claude says "no API available"
./odata-mcp https://large-sap-service.com/odata/

# After: 1 tool, ~900 tokens, works perfectly
./odata-mcp --universal https://large-sap-service.com/odata/

Metric	Standard Mode	Universal Mode	Reduction
Tools (Northwind)	157	1	99.4%
Tools (SAP BP)	485	1	99.8%
Token usage	~37,000	~900	97.6%

Why is it opt-in? Universal mode changes how you interact with OData:

Standard mode: Each entity gets dedicated tools (filter_Products, get_Orders, etc.)
Universal mode: One odata tool with action, target, and params

We made it opt-in because:

Backward compatibility — existing configs and workflows continue working
Discoverability — per-entity tools are self-documenting; LLMs can see exactly what's available
Simplicity for small services — if you have 20 tools, per-entity mode works great
Explicit choice — users should consciously choose the trade-off

When to use --universal:

Service has 50+ entity sets
Running multiple OData services simultaneously
Experiencing "no API available" or tool selection failures
Want minimal token footprint

See Universal Tool Architecture for the full story.

MCP Header Forwarding

New --forward-mcp-headers flag enables passing HTTP headers from MCP clients to OData services:

Copy & paste — that's it

./odata-mcp --transport streamable-http --forward-mcp-headers https://secured-service.com/odata/

This enables:

Dynamic authentication — pass credentials per-request instead of at startup
Multi-tenant scenarios — different users with different tokens
Custom headers — X-* headers flow through to OData

Issue Fixes Bonanza

This release fixes 10 open issues:

Issue	Problem	Fix
#12	SAP OData shows no tools	Fixed XML namespace parsing (`sap:creatable` etc.)
#13	`--max-items 99999` crashes	Added validation (max 10,000)
#14	Multiple services = Claude stuck	Universal tool mode
#16	GUID formatting wrong	Auto-detect SAP, add `guid'...'` prefix
#17	Timeout instead of error	Immediate error response
#18	Wildcard search fails	Parse `SearchRestrictions` annotation
#19	Timeout hides SAP error	Return actual error message
#22	BaseType not exposed	Added to EntityType model
#23	Header handling	`--forward-mcp-headers` flag
#25	Windows build no .exe	Fixed Makefile for Windows

Previous Releases

AI Foundry Compatibility (v1.5.1): --protocol-version flag for AI Foundry's 2025-06-18 protocol
SAP GUID Filtering (v1.5.0): Automatic guid'...' formatting for SAP services
Streamable HTTP Transport (v1.5.0): Modern MCP protocol with --transport streamable-http

Features

Universal OData Support: Works with both OData v2 and v4 services
Dynamic Tool Generation: Automatically creates MCP tools based on OData metadata
Multiple Authentication Methods: Basic auth, cookie auth, and anonymous access
SAP OData Extensions: Full support for SAP-specific OData features including CSRF tokens
Comprehensive CRUD Operations: Generated tools for create, read, update, delete operations
Advanced Query Support: OData query options ($filter, $select, $expand, $orderby, etc.)
Function Import Support: Call OData function imports as MCP tools
Flexible Tool Naming: Configurable tool naming with prefix/postfix options
Entity Filtering: Selective tool generation with wildcard support
Cross-Platform: Native Go binary for easy deployment on any OS
Read-Only Modes: Restrict operations with --read-only or --read-only-but-functions
MCP Protocol Debugging: Built-in trace logging with --trace-mcp for troubleshooting
Service-Specific Hints: Flexible hint system with pattern matching for known service issues
Full MCP Compliance: Complete protocol implementation for all MCP clients
Multiple Transports: Support for stdio (default), HTTP/SSE, and Streamable HTTP
AI Foundry Compatible: Configurable protocol version for AI Foundry and other MCP clients

Generated Tools

The bridge automatically generates MCP tools based on the OData service metadata:

Entity Set Tools

For each entity set, the following tools are generated (if the entity set supports the operation):

filter_{EntitySet} - List/filter entities with OData query options
count_{EntitySet} - Get count of entities with optional filter
search_{EntitySet} - Full-text search (if supported by the service)
get_{EntitySet} - Get a single entity by key
create_{EntitySet} - Create a new entity (if allowed)
update_{EntitySet} - Update an existing entity (if allowed)
delete_{EntitySet} - Delete an entity (if allowed)

Function Import Tools

Each function import is mapped to an individual tool with the function name.

Service Information Tool

odata_service_info - Get metadata and capabilities of the OData service

Examples

Northwind Service (v2)

Copy & paste — that's it

# Connect to the public Northwind OData v2 service
./odata-mcp --trace https://services.odata.org/V2/Northwind/Northwind.svc/

# This will show generated tools like:
# - filter_Products_for_northwind
# - get_Products_for_northwind  
# - filter_Categories_for_northwind
# - get_Orders_for_northwind
# - etc.

Northwind Service (v4)

Copy & paste — that's it

# Connect to the public Northwind OData v4 service
./odata-mcp --trace https://services.odata.org/V4/Northwind/Northwind.svc/

# OData v4 is automatically detected and handled appropriately
# Supports v4 specific features like:
# - $count parameter instead of $inlinecount
# - contains() filter function
# - New data types (Edm.Date, Edm.TimeOfDay, etc.)

SAP OData Service

Copy & paste — that's it

# Connect to SAP service with CSRF token support
./odata-mcp --user admin --password secret \
  https://my-sap-system.com/sap/opu/odata/sap/SERVICE_NAME/

Differences from Python Version

While maintaining the same CLI interface and functionality, this Go implementation offers:

Better Performance: Native compiled binary with lower memory usage
Easier Deployment: Single binary with no runtime dependencies
Cross-Platform: Native binaries for Windows, macOS, and Linux
Type Safety: Go's type system provides better reliability
Simpler Installation: No need for Python runtime or package management

Versioning

This project uses automatic versioning based on git tags and commit history:

Tagged releases: Uses git tags (e.g., v1.0.0)
Development builds: Uses 0.1.<commit-count> format
Uncommitted changes: Appends -dirty suffix

Copy & paste — that's it

# Check current version
make version

# Create a release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

See VERSIONING.md for detailed versioning guide.

Releasing

This project uses automated GitHub Actions for releases. See RELEASING.md for the release process.

Security

This project includes comprehensive security measures to prevent credential leaks. See SECURITY.md for details.

Important: Never commit .zmcp.json or any files containing real credentials.

Documentation

QUICK_REFERENCE.md - Quick command reference
HINTS.md - Complete guide to the service hints system
TROUBLESHOOTING.md - Common issues and solutions
SECURITY.md - Security considerations
CHANGELOG.md - Version history and changes

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

For questions and community discussion, visit our GitHub Discussions.

Development

For development setup and testing:

Copy & paste — that's it

# Run tests
make test

# Run with verbose output for debugging
./odata-mcp --verbose --trace-mcp https://my-service.com/odata/

# Check MCP compliance
./simple_compliance_test.sh

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copy & paste — that's it

# Build Docker image
make docker

# Or manually
docker build -t odata-mcp .

# Run in container
docker run --rm -it odata-mcp --help

Before it works, you'll need: ODATA_USERNAMEODATA_PASSWORD

Installation

Download Binary

Download the appropriate binary for your platform from the releases page.

Pre-built binaries are available for:

Linux (amd64)
Windows (amd64)
macOS (Intel and Apple Silicon)

Build from Source

Quick Build (Go required)

Copy & paste — that's it

git clone https://github.com/oisee/odata_mcp_go.git
cd odata_mcp_go
go build -o odata-mcp cmd/odata-mcp/main.go

Using Makefile (Recommended)

Copy & paste — that's it

# Build for current platform
make build

# Build for all platforms
make build-all

# Build for all platforms with WSL integration (copies to /mnt/c/bin)
make build-all-wsl

# Build and test
make dev

# Check current version
make version

# See all options
make help

Using Build Script

Copy & paste — that's it

# Build for current platform
./build.sh

# Build for all platforms
./build.sh all

# See all options
./build.sh help

Cross-Compilation Examples

Copy & paste — that's it

# Using Make
make build-linux     # Linux (amd64)
make build-windows   # Windows (amd64)
make build-macos     # macOS (Intel + Apple Silicon)

# WSL-specific builds (copies Windows binary to /mnt/c/bin)
make build-windows-wsl  # Build Windows + WSL integration
make build-all-wsl      # Build all platforms + WSL integration

# Using build script
./build.sh linux     # Linux (amd64)
./build.sh windows   # Windows (amd64)
./build.sh macos     # macOS (Intel + Apple Silicon)

# Manual Go build
GOOS=linux GOARCH=amd64 go build -o odata-mcp-linux cmd/odata-mcp/main.go
GOOS=windows GOARCH=amd64 go build -o odata-mcp.exe cmd/odata-mcp/main.go

Docker Build

Copy & paste — that's it

# Build Docker image
make docker

# Or manually
docker build -t odata-mcp .

# Run in container
docker run --rm -it odata-mcp --help

Building in WSL (Windows Subsystem for Linux)

When building in WSL, you can use special targets that automatically copy the Windows binary to your Windows file system:

Copy & paste — that's it

# Build all platforms and copy Windows binary to C:\bin
make build-all-wsl

# Build only Windows and copy to C:\bin
make build-windows-wsl

Note: These commands will check if /mnt/c/bin exists and skip the copy if not found, so they're safe to use on any system.

Usage

Claude Desktop Configuration

Claude Desktop uses the stdio transport by default. Here are example configurations:

Finding Your Configuration File

The Claude Desktop configuration file location varies by platform:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Basic Configuration

Copy & paste — that's it

{
    "mcpServers": {
        "northwind-v2": {
            "command": "C:/bin/odata-mcp.exe",
            "args": [
                "--service",
                "https://services.odata.org/V2/Northwind/Northwind.svc/",
                "--tool-shrink"
            ]
        },
        "northwind-v4": {
            "command": "C:/bin/odata-mcp.exe",
            "args": [
                "--service",
                "https://services.odata.org/V4/Northwind/Northwind.svc/",
                "--tool-shrink"
            ]
        }
    }
}

With Authentication

Copy & paste — that's it

{
    "mcpServers": {
        "my-sap-service": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://my-sap-system.com/sap/opu/odata/sap/MY_SERVICE/",
                "--user",
                "myusername",
                "--password",
                "mypassword",
                "--tool-shrink",
                "--entities",
                "Products,Orders,Customers"
            ]
        }
    }
}

Using Environment Variables (More Secure)

Copy & paste — that's it

{
    "mcpServers": {
        "my-secure-service": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://my-service.com/odata/",
                "--tool-shrink"
            ],
            "env": {
                "ODATA_USERNAME": "myusername",
                "ODATA_PASSWORD": "mypassword"
            }
        }
    }
}

Note: Claude Desktop currently doesn't support reading environment variables from your system. The env field in the configuration sets environment variables specifically for that MCP server process.

Security Best Practices for Claude Desktop

Use environment variables in the env field rather than hardcoding credentials in args
Limit entity access using the --entities flag to only expose necessary data
Use read-only accounts when possible for OData services
Store configuration file securely with appropriate file permissions

Note: Claude Desktop does not currently support API key authentication for MCP servers. All MCP servers run locally with the same permissions as Claude Desktop itself.

Read-Only Configuration Examples

Copy & paste — that's it

{
    "mcpServers": {
        "production-readonly": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://production.company.com/odata/",
                "--read-only",
                "--tool-shrink"
            ],
            "env": {
                "ODATA_USERNAME": "readonly_user",
                "ODATA_PASSWORD": "readonly_pass"
            }
        },
        "dev-with-functions": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service", 
                "https://dev.company.com/odata/",
                "--read-only-but-functions",
                "--trace-mcp"  // Enable debugging
            ]
        }
    }
}

Claude Code CLI Compatibility

The Claude Code CLI has stricter property name validation than other Claude tools. If you encounter errors like:

Copy & paste — that's it

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools.17.custom.input_schema.properties: Property keys should match pattern ^[a-zA-Z0-9_.-]{1,64}$"}}

Use the --claude-code-friendly flag to remove the $ prefix from OData parameter names:

Copy & paste — that's it

{
    "mcpServers": {
        "northwind-claude-code": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://services.odata.org/V2/Northwind/Northwind.svc/",
                "--claude-code-friendly",  // Removes $ from parameter names
                "--tool-shrink"
            ]
        }
    }
}

This transforms parameter names:

$filter → filter
$select → select
$expand → expand
$orderby → orderby
$top → top
$skip → skip
$count → count

The server internally maps these friendly names back to their OData equivalents when making requests.

Operation Filtering Configuration Examples

Copy & paste — that's it

{
    "mcpServers": {
        "large-service-readonly": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://large-erp.company.com/odata/",
                "--disable", "cud",  // Disable create, update, delete
                "--tool-shrink",
                "--entities", "Orders,Products,Customers"
            ],
            "env": {
                "ODATA_USERNAME": "readonly_user",
                "ODATA_PASSWORD": "readonly_pass"
            }
        },
        "minimal-tools": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://api.company.com/odata/",
                "--enable", "gf",  // Only get and filter operations
                "--tool-shrink"
            ]
        },
        "no-actions": {
            "command": "/usr/local/bin/odata-mcp", 
            "args": [
                "--service",
                "https://api.company.com/odata/",
                "--disable", "a",  // Disable all function imports/actions
                "--verbose"
            ]
        }
    }
}

### AI Foundry Configuration

For AI Foundry integration, use the `--protocol-version` flag to specify the `2025-06-18` protocol:

```json
{
    "mcpServers": {
        "odata-for-ai-foundry": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://your-odata-service.com/",
                "--protocol-version", "2025-06-18",
                "--user", "your-username",
                "--password", "your-password"
            ]
        }
    }
}

Or via command line:

Copy & paste — that's it

./odata-mcp --service https://your-service.com/odata --protocol-version "2025-06-18"

See the AI Foundry Compatibility Guide for detailed setup instructions.

Transport Options

The OData MCP bridge supports two transport mechanisms:

STDIO (default) - Standard input/output communication, used by Claude Desktop
HTTP/SSE - HTTP server with Server-Sent Events for web-based clients

🔒 SECURITY MODEL: HTTP transport uses a strict security model.

Security Requirements:

Localhost: Token required (--mcp-token)

Non-localhost: Token + TLS required, no exceptions

All interfaces (0.0.0.0/::): Requires --allow-all-interfaces + token + TLS

Token can be any string - for dev, --mcp-token dev works fine.

Using Streamable HTTP Transport (Modern MCP Protocol)

New in v1.5.0: Support for Streamable HTTP transport (protocol version 2024-11-05)

Copy & paste — that's it

# Start server with Streamable HTTP (recommended for modern clients)
./odata-mcp --transport streamable-http https://services.odata.org/V2/Northwind/Northwind.svc/

# Use custom localhost port
./odata-mcp --transport streamable-http --http-addr localhost:3000 https://services.odata.org/V2/Northwind/Northwind.svc/

Streamable HTTP endpoints:

POST /mcp - Main MCP endpoint (supports automatic SSE upgrade)
GET /health - Health check endpoint
POST /sse - Legacy SSE endpoint (for backward compatibility)

Using HTTP/SSE Transport (Legacy)

Copy & paste — that's it

# Start server on localhost (default: localhost:8080)
./odata-mcp --transport http --mcp-token "dev" https://services.odata.org/V2/Northwind/Northwind.svc/

# Use custom localhost port
./odata-mcp --transport http --http-addr localhost:3000 --mcp-token "dev" https://services.odata.org/V2/Northwind/Northwind.svc/

# Non-localhost requires token + TLS
./odata-mcp --transport http --http-addr 192.168.1.100:8080 \
  --mcp-token "my-secret-token" --tls --tls-cert cert.pem --tls-key key.pem \
  https://services.odata.org/V2/Northwind/Northwind.svc/

# All interfaces requires explicit flag + token + TLS
./odata-mcp --transport http --http-addr 0.0.0.0:8080 \
  --allow-all-interfaces --mcp-token "my-secret-token" \
  --tls --tls-cert cert.pem --tls-key key.pem \
  https://services.odata.org/V2/Northwind/Northwind.svc/

Legacy HTTP/SSE endpoints:

GET /health - Health check endpoint
GET /sse - Server-Sent Events endpoint for real-time communication
POST /rpc - JSON-RPC endpoint for request/response communication

Testing HTTP/SSE Transport

Using the provided HTML client:

Copy & paste — that's it

# Start the server
./odata-mcp --transport http https://services.odata.org/V2/Northwind/Northwind.svc/

# Open examples/sse_client.html in a web browser

Using curl:

Copy & paste — that's it

# Test SSE endpoint
curl -N -H 'Accept: text/event-stream' http://localhost:8080/sse

# Test RPC endpoint
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Using the test scripts:

Copy & paste — that's it

# Test SSE with interactive script
./test_sse.sh

# Test HTTP/RPC communication
./test_http_rpc.sh

Basic Usage

Copy & paste — that's it

# Using positional argument
./odata-mcp https://services.odata.org/V2/Northwind/Northwind.svc/

# Using --service flag
./odata-mcp --service https://services.odata.org/V2/Northwind/Northwind.svc/

# Using environment variable
export ODATA_SERVICE_URL=https://services.odata.org/V2/Northwind/Northwind.svc/
./odata-mcp

Authentication

Copy & paste — that's it

# Basic authentication
./odata-mcp --user admin --password secret https://my-service.com/odata/

# Cookie file authentication
./odata-mcp --cookie-file cookies.txt https://my-service.com/odata/

# Cookie string authentication  
./odata-mcp --cookie-string "session=abc123; token=xyz789" https://my-service.com/odata/

# Environment variables
export ODATA_USERNAME=admin
export ODATA_PASSWORD=secret
./odata-mcp https://my-service.com/odata/

Tool Naming Options

Copy & paste — that's it

# Use custom prefix instead of postfix
./odata-mcp --no-postfix --tool-prefix "myservice" https://my-service.com/odata/

# Use custom postfix
./odata-mcp --tool-postfix "northwind" https://my-service.com/odata/

# Use shortened tool names
./odata-mcp --tool-shrink https://my-service.com/odata/

Entity and Function Filtering

Copy & paste — that's it

# Filter to specific entities (supports wildcards)
./odata-mcp --entities "Products,Categories,Order*" https://my-service.com/odata/

# Filter to specific functions (supports wildcards)  
./odata-mcp --functions "Get*,Create*" https://my-service.com/odata/

Read-Only Modes

Copy & paste — that's it

# Hide all modifying operations (create, update, delete, and functions)
./odata-mcp --read-only https://my-service.com/odata/
./odata-mcp -ro https://my-service.com/odata/  # Short form

# Hide create/update/delete but allow function imports
./odata-mcp --read-only-but-functions https://my-service.com/odata/
./odata-mcp -robf https://my-service.com/odata/  # Short form

Operation Type Filtering

Fine-grained control over which operation types are available. Operation types are:

C - Create operations
S - Search operations
F - Filter/list operations
G - Get (single entity) operations
U - Update operations
D - Delete operations
A - Actions/function imports
R - Read operations (expands to S, F, G)

Copy & paste — that's it

# Enable only read operations (search, filter, get)
./odata-mcp --enable "r" https://my-service.com/odata/
./odata-mcp --enable "sfg" https://my-service.com/odata/  # Same as above

# Disable all modifying operations
./odata-mcp --disable "cud" https://my-service.com/odata/

# Enable only get and filter operations
./odata-mcp --enable "gf" https://my-service.com/odata/

# Disable actions/function imports
./odata-mcp --disable "a" https://my-service.com/odata/

# Case-insensitive
./odata-mcp --disable "CUD" https://my-service.com/odata/

Note: --enable and --disable cannot be used together.

Universal Tool Mode

For large OData services with many entities, the standard per-entity tool generation can create hundreds of tools, causing:

Context rot: LLMs struggle to reason when tool count exceeds ~128
High token usage: Tool schemas can consume 15,000-40,000 tokens
Tool selection failures: LLMs may report "no API available"

Universal mode solves this by generating a single tool that handles all operations:

Copy & paste — that's it

# Enable universal tool mode
./odata-mcp --universal https://my-service.com/odata/

# Compare tool counts
./odata-mcp --trace https://my-service.com/odata/           # Standard: many tools
./odata-mcp --universal --trace https://my-service.com/odata/  # Universal: 1 tool

When to use universal mode:

Service has more than ~50 entity sets
Using multiple OData services simultaneously
Experiencing "no API available" errors with large services

Universal tool usage:

Copy & paste — that's it

{"action": "list", "target": "Products", "params": {"filter": "Price gt 100", "top": 10}}
{"action": "get", "target": "Products", "params": {"key": {"ProductID": 1}}}
{"action": "create", "target": "Orders", "params": {"data": {"CustomerID": "C001"}}}
{"action": "call", "target": "ReleaseOrder", "params": {"OrderID": "O001"}}

Debugging and Inspection

Copy & paste — that's it

# Enable verbose output
./odata-mcp --verbose https://my-service.com/odata/

# Trace mode - show all tools without starting server
./odata-mcp --trace https://my-service.com/odata/

# Enable MCP protocol trace logging (saves to temp directory)
./odata-mcp --trace-mcp https://my-service.com/odata/
# Linux/WSL: /tmp/mcp_trace_*.log
# Windows: %TEMP%\mcp_trace_*.log

Service Hints

The OData MCP bridge includes a flexible hint system to provide guidance for services with known issues or special requirements:

Copy & paste — that's it

# Use default hints.json from binary directory
./odata-mcp https://my-service.com/odata/

# Use custom hints file
./odata-mcp --hints-file /path/to/custom-hints.json https://my-service.com/odata/

# Inject hint directly from command line
./odata-mcp --hint "Remember to use \$expand for complex queries" https://my-service.com/odata/

# Combine file and CLI hints (CLI has higher priority)
./odata-mcp --hints-file custom.json --hint '{"notes":["Override note"]}' https://my-service.com/odata/

Configuration

Command Line Flags

Flag	Description	Default
`--service`	OData service URL
`-u, --user`	Username for basic auth
`-p, --password`	Password for basic auth
`--cookie-file`	Path to cookie file (Netscape format)
`--cookie-string`	Cookie string (key1=val1; key2=val2)
`--tool-prefix`	Custom prefix for tool names
`--tool-postfix`	Custom postfix for tool names
`--no-postfix`	Use prefix instead of postfix	`false`
`--tool-shrink`	Use shortened tool names	`false`
`--entities`	Comma-separated entity filter (supports wildcards)
`--functions`	Comma-separated function filter (supports wildcards)
`--sort-tools`	Sort tools alphabetically	`true`
`-v, --verbose`	Enable verbose output	`false`
`--debug`	Alias for --verbose	`false`
`--trace`	Show tools and exit (debug mode)	`false`
`--trace-mcp`	Enable MCP protocol trace logging	`false`
`--read-only, -ro`	Hide all modifying operations	`false`
`--read-only-but-functions, -robf`	Hide create/update/delete but allow functions	`false`
`--enable`	Enable only specified operation types (C,S,F,G,U,D,A,R)
`--disable`	Disable specified operation types (C,S,F,G,U,D,A,R)
`--hints-file`	Path to hints JSON file	`hints.json` in binary dir
`--hint`	Direct hint JSON or text from CLI
`--transport`	Transport type: 'stdio', 'http' (SSE), or 'streamable-http'	`stdio`
`--http-addr`	HTTP server address (with --transport http/streamable-http)	`localhost:8080`
`--mcp-token`	Authentication token for HTTP transport (required)
`--mcp-token-file`	Path to file containing authentication token
`--tls`	Enable TLS for HTTP transport	`false`
`--tls-cert`	Path to TLS certificate file
`--tls-key`	Path to TLS key file
`--allow-all-interfaces`	Allow binding to 0.0.0.0/:: (requires --mcp-token and --tls)	`false`
`--legacy-dates`	Enable legacy date format conversion	`true`
`--no-legacy-dates`	Disable legacy date format conversion	`false`
`--convert-dates-from-sap`	Convert SAP date formats in responses	`false`
`--response-metadata`	Include __metadata blocks in responses	`false`
`--pagination-hints`	Add pagination information to responses	`false`
`--max-response-size`	Maximum response size in bytes	`5MB`
`--max-items`	Maximum number of items in response	`100`
`--verbose-errors`	Provide detailed error context	`false`
`--claude-code-friendly, -c`	Remove $ prefix from OData parameters for Claude Code CLI compatibility	`false`
`--protocol-version`	Override MCP protocol version (e.g., '2025-06-18' for AI Foundry)	`2024-11-05`
`--forward-mcp-headers`	Forward HTTP headers from MCP connection to OData service (Streamable HTTP only)	`false`
`--universal`	Use single universal OData tool instead of per-entity tools (reduces context for large services)	`false`

Environment Variables

Variable	Description
`ODATA_SERVICE_URL` or `ODATA_URL`	OData service URL
`ODATA_USERNAME` or `ODATA_USER`	Username for basic auth
`ODATA_PASSWORD` or `ODATA_PASS`	Password for basic auth
`ODATA_COOKIE_FILE`	Path to cookie file
`ODATA_COOKIE_STRING`	Cookie string

.env File Support

Create a .env file in the working directory:

Copy & paste — that's it

ODATA_SERVICE_URL=https://my-service.com/odata/
ODATA_USERNAME=admin
ODATA_PASSWORD=secret

Troubleshooting

MCP Client Issues

If you're experiencing issues with MCP clients (Claude Desktop, RooCode, GitHub Copilot):

Enable trace logging to diagnose protocol issues:
Copy & paste — that's it
```
./odata-mcp --trace-mcp https://my-service.com/odata/
```
Then check the trace file in your temp directory.
Common issues and solutions:
- Tools not appearing: Ensure the service URL is correct and accessible
- Validation errors: Update to the latest version which includes MCP compliance fixes
- Connection failures: Check authentication credentials and network connectivity
Service-specific hints: The odata_service_info tool now includes automatic hints for known problematic services

See TROUBLESHOOTING.md for detailed troubleshooting guide.

Service Hints System

The OData MCP bridge includes a sophisticated hint system that helps users work around known service issues and provides implementation guidance.

Hint File Format

Create a hints.json file with the following structure:

Copy & paste — that's it

{
  "version": "1.0",
  "hints": [
    {
      "pattern": "*/sap/opu/odata/*",
      "priority": 10,
      "service_type": "SAP OData Service",
      "known_issues": ["List of known issues"],
      "workarounds": ["List of workarounds"],
      "field_hints": {
        "FieldName": {
          "type": "Edm.String",
          "format": "Expected format",
          "example": "12345",
          "description": "Field description"
        }
      },
      "examples": [
        {
          "description": "Example description",
          "query": "filter_EntitySet with $filter=...",
          "note": "Additional note"
        }
      ]
    }
  ]
}

Pattern Matching

The hint system supports wildcard patterns:

* matches any sequence of characters
? matches a single character
Multiple patterns can match the same service (hints are merged by priority)

Default Hints

The bridge includes default hints for common services:

SAP OData Services (*/sap/opu/odata/*): General SAP OData guidance including the critical workaround for HTTP 501 errors using $expand
SAP PO Tracking (*SRA020_PO_TRACKING_SRV*): Specific hints for purchase order tracking including field formatting
Northwind Demo (*Northwind*): Identifies the public demo service

Using Hints

Hints appear in the odata_service_info tool response under implementation_hints:

Copy & paste — that's it

# View hints for your service
./odata-mcp https://my-service.com/odata/
# Then call the odata_service_info tool in your MCP client

# The response includes:
{
  "implementation_hints": {
    "service_type": "SAP OData Service",
    "known_issues": [...],
    "workarounds": [...],
    "field_hints": {...},
    "examples": [...],
    "hint_source": "Hints file: hints.json"
  }
}