MCP Server Connection Guide

Collate provides a Model Context Protocol (MCP) server that lets AI assistants and other clients interact with your metadata catalog. The MCP server exposes tools for searching metadata, managing glossaries, and working with lineage data. See the guides for Claude and Goose if you’re using them as AI assistants.

Server Information

Server Name: openmetadata-mcp-stateless.
Version: 1.1.0.
Endpoint: https://<YOUR-Collate-SERVER>/mcp.
Protocol: Streamable HTTP (single POST /mcp endpoint). SSE is used only when explicitly requested by the client.
Authentication: OAuth 2.0 (recommended) or JWT Bearer Token (Personal Access Token).

Connection Setup

1. Server URL

Your MCP server is available at:

https://<YOUR-Collate-SERVER>/mcp

Replace <YOUR-Collate-SERVER> with your Collate instance URL, for example your-collate-instance.com.

2. Authentication

The MCP server supports two authentication methods:

OAuth 2.0 (interactive clients): Sign in with your existing Collate credentials. Requires a browser and a signed-in user, so it isn’t suitable for headless or unattended agents. See OAuth 2.0 Authentication.
Bot JWT Token: For unattended agents and environments where browser-based login is unavailable. Generate a token from a Bot as described in Bot JWT Token, then include it in every request:

Authorization: Bearer <your-jwt-token>

3. Content Type

All requests should use:

Content-Type: application/json

API Endpoints

Initialize Connection

Endpoint: POST <YOUR-Collate-SERVER>/mcp Sample Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {},
      "prompts": {},
      "resources": {
        "subscribe": true,
        "listChanged": true
      }
    },
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

Sample Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {},
      "prompts": {},
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "logging": {}
    },
    "serverInfo": {
      "name": "openmetadata-mcp-stateless",
      "version": "1.1.0"
    }
  }
}

List Available Tools

Endpoint: POST <YOUR-Collate-SERVER>/mcp Collate exposes 26 tools in total. The sample response below shows the shape of two tools. For the full list with parameters and examples, see the MCP Tools Reference. Sample Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Sample Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "search_metadata",
        "description": "Find your data and business terms in OpenMetadata. For example if the user asks to 'find tables that contain customers information', then 'customers' should be the query, and the entity_type should be 'table'. Here make sure to use 'Href' is available in result to create a hyperlink to the entity in OpenMetadata.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Keywords to use for searching."
            },
            "entity_type": {
              "type": "string",
              "description": "Optional entity type to filter results..."
            },
            "limit": {
              "type": "integer",
              "description": "Maximum number of results to return. Default is 10."
            },
            "fields": {
              "type": "string",
              "description": "Comma-separated list of additional fields to include..."
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "get_entity_details",
        "description": "Get detailed information about a specific entity",
        "inputSchema": {
          "type": "object",
          "properties": {
            "entity_type": {
              "type": "string",
              "description": "Type of entity"
            },
            "fqn": {
              "type": "string",
              "description": "Fully qualified name of the entity"
            }
          },
          "required": ["entity_type", "fqn"]
        }
      }
    ]
  }
}

List Available Prompts

Endpoint: POST <YOUR-Collate-SERVER>/mcp Sample Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "prompts/list"
}

Sample Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "prompts": [
      {
        "name": "search_metadata",
        "description": "Creates a prompt for Searching metadata in OpenMetadata.",
        "arguments": [
          {
            "name": "query",
            "description": "Keywords to use for searching.",
            "required": true
          },
          {
            "name": "entity_type",
            "description": "Entity Type to Filter Report."
          },
          {
            "name": "limit",
            "description": "Maximum number of results to return. Default is 10."
          }
        ]
      }
    ]
  }
}

Call a Tool

Endpoint: POST <YOUR-Collate-SERVER>/mcp Sample Request (Search Metadata):

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_metadata",
    "arguments": {
      "query": "customer",
      "entity_type": "table",
      "limit": 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 <YOUR-Collate-SERVER>/mcp Sample Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/get",
  "params": {
    "name": "search_metadata",
    "arguments": {
      "query": "customer tables",
      "entity_type": "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 plain error body, not a full JSON-RPC envelope:

{
  "code": -32603,
  "message": "Invalid or expired token"
}

The same message and code are used whether the token is missing, invalid, or expired. 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 entity_type to get more relevant results.

Security Considerations

JWT tokens should stay secure and shouldn’t be 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, check out our blog.

Reach Out on Slack

With MCP, Collate users are finding new ways to use the platform all the time. If you’ve got a great new use case, show it off in Slack.

​MCP Server Connection Guide

​Server Information

​Connection Setup

​1. Server URL

​2. Authentication

​3. Content Type

​API Endpoints

​Initialize Connection

​List Available Tools

​List Available Prompts

​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

MCP Server Connection Guide

Server Information

Connection Setup

1. Server URL

2. Authentication

3. Content Type

API Endpoints

Initialize Connection

List Available Tools

List Available Prompts

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