Build custom integrations

This topic includes raw HTTP/curl examples for connecting to the MCP server, along with the full tool reference needed to build your own client, script, or integration.

In this topic:

Overview

Use the sections in this topic to build and validate a custom integration:

1. Generic HTTP client (curl): Use the curl requests to verify endpoint access, authenticate, list tools, and run an initial tool call.

2. Tool reference: Implement each tool in your integration using the documented parameters, examples, and response formats.

3. End-to-end workflow example: Use the example sequence as a template for the order of tool calls in your own integration flow.

4. Register the integration: Register the integration in the OpenText Core Software Delivery Platform authorization server with a unique client_name and the allowed redirect_uris. Submit a support ticket and include the client_name and redirect_uris.

Generic HTTP client (curl)

Use this to test the connection or build custom integrations.

Discover available tools:

curl -s -X POST https://myoctane.company.com/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

Call a tool:

curl -s -X POST https://myoctane.company.com/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "get_entities",
      "arguments": {
        "sharedSpaceId": 1001,
        "workSpaceId": 1002,
        "entityType": "defect",
        "fields": ["id", "name", "severity"],
        "limit": 10
      }
    }
  }'

Successful response shape:

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [{ "type": "text", "text": "{ \"entities\": [...] }" }]
  }
}

Error response shape (business-logic error, HTTP 200):

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [{ "type": "text", "text": "User validation failed in shared space 1001" }],
    "isError": true
  }
}

Tool reference

All tools require sharedSpaceId and workSpaceId. Every call is scoped to a single workspace.

get_entity_types

List all entity types available in the workspace - names, labels, aggregate groups, and descriptors.

Call this first to discover valid entityType values for other tools.

Parameters

Example

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_entity_types",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002
    }
  }
}

Response (excerpt)

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"aggregates\": [ { \"name\": \"defect\", \"label\": \"Defect\", ... }, { \"name\": \"story\", \"label\": \"User Story\", ... } ] }"
    }]
  }
}

get_entity_field_metadata

Return field definitions for a given entity type - field names, types, labels, and other attributes.

Call this before get_entities or get_entity to know which fields to request or filter on.

Parameters

Example

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_entity_field_metadata",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect"
    }
  }
}

Response (excerpt)

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"fields\": [ { \"name\": \"severity\", \"label\": \"Severity\", \"field_type\": \"reference\", ... }, { \"name\": \"phase\", \"label\": \"Phase\", ... } ] }"
    }]
  }
}

get_filter_metadata

Return the Octane filter query syntax documentation - operators, value formats, logical connectors, and special tokens.

Call this before building any filter expression for get_entities.

Parameters

Example

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_filter_metadata",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002
    }
  }
}

get_entities

Retrieve a paginated list of entities of the same type. Supports structured filtering, full-text keyword search, field selection, sorting, and pagination.

Parameters

Example - filter by severity and phase

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_entities",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "filter": "(severity EQ {id='list_node.severity.critical'} || severity EQ {id='list_node.severity.high'}) ; !(phase EQ {id='list_node.defect.phase.closed'})",
      "fields": ["id", "name", "severity", "phase", "owner"],
      "orderBy": "-id",
      "limit": 25
    }
  }
}

Example - keyword search

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_entities",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "story",
      "keywords": "login performance",
      "fields": ["id", "name", "story_points", "phase"],
      "limit": 10
    }
  }
}

Example - pagination

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_entities",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "fields": ["id", "name"],
      "limit": 100,
      "offset": 100
    }
  }
}

Response (excerpt)

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"entities\": [ { \"id\": 1005, \"name\": \"Login fails on Safari\", \"severity\": { \"id\": \"list_node.severity.critical\" } }, ... ] }"
    }]
  }
}

get_entity

Retrieve a single entity by its numeric ID.

Parameters

Example

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_entity",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "entityId": 3042,
      "fields": ["id", "name", "description", "severity", "phase", "owner", "creation_time"]
    }
  }
}

Response

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"id\": 3042, \"name\": \"Login fails on Safari\", \"severity\": { \"id\": \"list_node.severity.critical\" }, ... }"
    }]
  }
}

Entity not found response (not an error, HTTP 200):

{
  "result": {
    "content": [{ "type": "text", "text": "entity 3042 not found" }]
  }
}

Write tools require the Use MCP Write operations permission in addition to Access MCP Server. For details, see Roles and permissions.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "create_entity",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "field_values": {
        "name": "Login button unresponsive on mobile",
        "severity": {"id": "list_node.severity.high"},
        "parent": {"id": 2010}
      }
    }
  }
}

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"status\": \"created\", \"id\": 4051, \"name\": \"Login button unresponsive on mobile\", \"link\": \"https://myoctane.company.com/ui/?p=1001/1002#/entity-navigation?entityType=defect&id=4051\" }"
    }]
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "update_entity",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "entityId": 4051,
      "field_values": {
        "severity": {"id": "list_node.severity.critical"},
        "phase": {"id": "list_node.defect.phase.closed"}
      }
    }
  }
}

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"status\": \"updated\", \"id\": 4051, \"name\": \"Login button unresponsive on mobile\", \"link\": \"https://myoctane.company.com/ui/?p=1001/1002#/entity-navigation?entityType=defect&id=4051\" }"
    }]
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "add_comment",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "entityId": 4051,
      "field_values": {
        "text": "<html><body><p>Investigating this issue.</p></body></html>"
      }
    }
  }
}

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"status\": \"created\", \"id\": 6001, \"link\": \"https://myoctane.company.com/ui/?p=1001/1002#/entity-navigation?entityType=defect&id=4051\" }"
    }]
  }
}

End-to-end workflow example

This section shows a complete interaction pattern an AI assistant would follow to answer: "List all open critical defects in release 2005, and create a tracking story for the top one."

Discover entity types

{ "method": "tools/call", "params": { "name": "get_entity_types",
  "arguments": { "sharedSpaceId": 1001, "workSpaceId": 1002 } } }

Confirms defect and story are valid types.

Inspect defect fields

{ "method": "tools/call", "params": { "name": "get_entity_field_metadata",
  "arguments": { "sharedSpaceId": 1001, "workSpaceId": 1002, "entityType": "defect" } } }

Learns field names: severity, phase, release, name, description, owner, id.

Learn filter syntax

{ "method": "tools/call", "params": { "name": "get_filter_metadata",
  "arguments": { "sharedSpaceId": 1001, "workSpaceId": 1002 } } }

Confirms operators and reference value format.

Query open critical defects in release 2005

{
  "method": "tools/call",
  "params": {
    "name": "get_entities",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "filter": "severity EQ {id='list_node.severity.critical'} ; !(phase EQ {id='list_node.defect.phase.closed'}) ; release EQ {id=2005}",
      "fields": ["id", "name", "severity", "phase", "owner"],
      "orderBy": "-id",
      "limit": 10
    }
  }
}

Returns a list of matching defects.

Retrieve full details of the top defect

{
  "method": "tools/call",
  "params": {
    "name": "get_entity",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "defect",
      "entityId": 4051,
      "fields": ["id", "name", "description", "severity", "phase", "owner", "release"]
    }
  }
}

Inspect story fields

{ "method": "tools/call", "params": { "name": "get_entity_field_metadata",
  "arguments": { "sharedSpaceId": 1001, "workSpaceId": 1002, "entityType": "story" } } }

Learns required fields for creating a story (e.g. name, parent).

{
  "method": "tools/call",
  "params": {
    "name": "create_entity",
    "arguments": {
      "sharedSpaceId": 1001,
      "workSpaceId": 1002,
      "entityType": "story",
      "field_values": {
        "name": "Track and resolve critical login defect #4051",
        "parent": {"id": 3001}
      }
    }
  }
}