MCP Server - API Usage & Reference

API Endpoints

Call a Tool

Endpoint: POST {OMURL}/mcp Sample Request (Search Metadata):

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_metadata",
    "arguments": {
      "query": "customer",
      "entityType": "table",
      "size": 5
    }
  }
}

Sample Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 results matching your search:\n\n1. **customer_orders** (Table)\n   - Description: Table containing customer order information\n   - Service: mysql_prod\n   - Database: ecommerce\n   - Schema: public\n   - [View in OpenMetadata](https://your-openmetadata.com/table/mysql_prod.ecommerce.public.customer_orders)\n\n2. **customer_profiles** (Table)\n   - Description: Customer profile and demographic data\n   - Service: postgresql_analytics\n   - Database: crm\n   - Schema: main\n   - [View in OpenMetadata](https://your-openmetadata.com/table/postgresql_analytics.crm.main.customer_profiles)\n\n3. **customer_events** (Table)\n   - Description: Customer interaction and event tracking\n   - Service: clickhouse_events\n   - Database: analytics\n   - Schema: events\n   - [View in OpenMetadata](https://your-openmetadata.com/table/clickhouse_events.analytics.events.customer_events)"
        }
      }
    ]
  }
}

Get a Prompt

Endpoint: POST {OMURL}/mcp Sample Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/get",
  "params": {
    "name": "search_metadata",
    "arguments": {
      "query": "customer tables",
      "entityType": "table",
      "limit": 10
    }
  }
}

Sample Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "description": "Creates a prompt for Searching metadata in OpenMetadata.",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Search for tables related to 'customer tables' in the OpenMetadata catalog. Filter results to show only 'table' entities and limit to 10 results. Look for tables that contain customer information, customer data, or are related to customer operations."
        }
      }
    ]
  }
}

Error Handling

Protocol-Level Errors

Authentication Error

A request with a missing or invalid/expired bearer token fails at the transport level: the server responds with HTTP status 401 Unauthorized (plus a WWW-Authenticate header identifying the OAuth authorization server) and a JSON-RPC 2.0 error body:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Missing bearer token"
  }
}

If a token is present but invalid or expired, message is "Invalid or expired bearer token" instead. Check the HTTP status code first: a 401 response means your client must (re-)authenticate before retrying, rather than treating the call as a normal JSON-RPC tool error.

Invalid Tool Error

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32601,
    "message": "Tool not found: invalid_tool_name",
    "data": {
      "type": "tool_error"
    }
  }
}

Validation Error

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid parameters: missing required field 'query'",
    "data": {
      "type": "validation_error",
      "field": "query"
    }
  }
}

Tool Execution Errors

A tool that runs but fails (a bad argument, a missing entity, an authorization denial, or a backend fault) does not return a JSON-RPC protocol-level error object. Instead, the server returns a normal JSON-RPC success response whose result.isError field is true. The failure details are a JSON string inside result.content[0].text, and the same object is also available as result.structuredContent for clients that support it. Sample Response (entity not found):

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"Error executing tool: table instance for mysql_prod.ecommerce.public.missing_table not found\",\"statusCode\":404}"
      }
    ],
    "structuredContent": {
      "error": "Error executing tool: table instance for mysql_prod.ecommerce.public.missing_table not found",
      "statusCode": 404
    },
    "isError": true
  }
}

	Protocol-Level Error	Tool Execution Error
Top-level field	`error`	`result`
Signals	Malformed request, unknown method, transport/auth failure before dispatch	Tool ran but the operation itself failed (bad FQN, permission denied, backend fault)
Where to check	`response.error.code` / `.message`	`response.result.isError === true`, then parse `response.result.content[0].text` (or read `response.result.structuredContent` directly)
`statusCode` in payload	Not present	Present inside the JSON string / `structuredContent` (`400`, `403`, `404`, `429`, `500`, `504`)

Always check result.isError on a successful JSON-RPC response before assuming the tool call succeeded. A 200-shaped response isn’t proof the operation worked.

Best Practices

Always authenticate: Include the JWT token in every request
Handle errors gracefully: Check for error responses and handle them appropriately
Use appropriate limits: Don’t request too many results at once to avoid performance issues
Cache server capabilities: Store the results of the initialize call to avoid repeated requests
Use specific entity types: When possible, specify entityType to get more relevant results

Security Considerations

JWT tokens should be kept secure and not logged
Use HTTPS for all communications
Implement token refresh logic for long-running connections
Follow your organization’s security policies for API access

For more sample use cases with MCP please check out our blog!

Reach out on Slack!

With MCP, we are finding new ways to use OpenMetadata all the time! Think you’ve got a great new use case? Show us what you’ve got in Slack!

​MCP Server - API Usage & Reference

​API Endpoints

​Call a Tool

​Get a Prompt

​Error Handling

​Protocol-Level Errors

​Authentication Error

​Invalid Tool Error

​Validation Error

​Tool Execution Errors

​Best Practices

​Security Considerations

​Reach out on Slack!