Connect an MCP agent

ShrikeDB exposes a JSON-RPC MCP endpoint at /api/v1/mcp on its HTTP listener. An MCP client can discover tools, inspect profiles, retrieve prompt workflows, and submit typed semantic requests. The client supplies its language model; ShrikeDB validates and executes the database plan.

Before you begin

You need the server HTTP URL, a logical database ID, and credentials when authentication is enabled. Semantic query and MCP must be enabled. The relevant configuration is:

semantic_query:
  enabled: true
  rest_enabled: true
  mcp_enabled: true
  max_limit: 1000
  default_timeout_ms: 5000

The examples below use Bash, curl, and jq against the local single-tenant server. Set the selected database once:

export SHRIKEDB_HTTP='http://127.0.0.1:8182'
export SHRIKEDB_DATABASE='YOUR_DATABASE_ID'

For an authenticated deployment, add -H "Authorization: Bearer $SHRIKEDB_ACCESS_TOKEN" or an API-key header to each request. Use the deployment’s HTTPS endpoint for remote credentials.

Discover the tools

curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/mcp" \
  -H 'Content-Type: application/json' \
  -H "x-shrikedb-database: $SHRIKEDB_DATABASE" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  > tools.json
jq '.result.tools[] | {name, description, inputSchema}' tools.json

Each entry includes the required arguments and accepted types. A successful HTTP response can still contain a JSON-RPC error; inspect that field before consuming result.

A tools/call request has this structure:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "semantic_catalog",
    "arguments": {}
  }
}

name selects a tool and arguments contains that tool’s input object. Save such a request as a JSON file and send it with curl --data-binary @request.json using the same endpoint and headers.

Find a profile

curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/mcp" \
  -H 'Content-Type: application/json' \
  -H "x-shrikedb-database: $SHRIKEDB_DATABASE" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"semantic_catalog","arguments":{}}}'

Choose a profile that describes the loaded dataset. If the catalog is empty, an administrator must configure a profile pack or import a reviewed profile. Profiles and domain vocabulary explains that workflow. Domain-specific profiles are loaded only when explicitly configured or imported.

Get a prompt for the selected profile

Set these values to a real profile and a question about its data:

export SHRIKEDB_PROFILE='YOUR_PROFILE_ID'
export SHRIKEDB_QUESTION='Which products belong to each category?'
jq -n --arg profile "$SHRIKEDB_PROFILE" --arg question "$SHRIKEDB_QUESTION" \
  '{jsonrpc:"2.0",id:3,method:"prompts/get",params:{name:"semantic_intent_workflow",arguments:{profile_id:$profile,question:$question}}}' \
  > prompt-request.json
curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/mcp" \
  -H 'Content-Type: application/json' \
  -H "x-shrikedb-database: $SHRIKEDB_DATABASE" \
  --data-binary @prompt-request.json

The returned prompt includes the profile’s concepts, relationships, limits, and output contract. Pass that prompt to the client model to produce a SemanticQueryIntent. Review missing bindings or clarification questions before execution.

Compile, inspect, and execute

Use semantic_compile with the selected profile_id and the generated intent. Use semantic_explain to inspect the proposed plan, then semantic_execute with the reviewed request. The exact argument schemas are available in tools.json:

jq '.result.tools[] | select(.name == "semantic_compile" or .name == "semantic_explain" or .name == "semantic_execute")' tools.json

These tools accept structured concepts, relationships, output fields, and safety settings. Raw Cypher or SPARQL belongs in the direct query interface. Compilation checks the profile bindings and limits; execution additionally returns result rows and provenance.

When multiple dataset versions share a database, include the version property in each version-specific intent. For example, this intent counts Case nodes whose v property is the integer 10:

{
  "goal": "aggregate",
  "concepts": [{"concept": "Case", "binding": "c"}],
  "constraints": [{"binding": "c", "field": "v", "op": "eq", "value": 10}],
  "aggregate": {
    "group_by": [],
    "measures": [{"function": "count", "binding": "c", "alias": "cases"}]
  },
  "safety": {"limit": 1}
}

Supply it as the intent argument with the selected profile_id. The constraint is evaluated before the count. Use the same version constraint on related retrieval or pattern intents when their results should refer to one dataset version.

A profile with reviewed capability templates can also supply starter intents through semantic_capability_templates. semantic_reason returns candidate interpretations and diagnostics for a natural-language question. Inspect the selected interpretation instead of executing every candidate.

Longer conversations

Workflow tools retain probe observations, clarification answers, and candidate intents during an investigation. Start with semantic_workflow_start, then use the returned workflow ID in subsequent calls. Discover each tool’s arguments through tools/list.

Tool When to use it

semantic_workflow_probe

Add observations gathered from bounded data inspection.

semantic_workflow_answer

Record the user’s answer to a domain clarification.

semantic_conversation_refine

Add a more specific question as a new stage.

semantic_conversation_fork

Explore a branch while retaining the original conversation.

semantic_conversation_join

Combine compatible stages from the same tenant and database.

semantic_conversation_stages

Inspect the stage history and versions.

Conversation state expires and is lost on server restart. Save transcripts in your client if you need a durable record. A workflow candidate still goes through normal compilation and execution permissions.

Profile feedback

semantic_feedback records a proposed correction. Alignment changes remain drafts until an authorized user reviews and publishes them through the alignment tools. Record the profile and alignment hashes returned with an answer when comparing results before and after a profile change.

Troubleshooting

Response Action

MCP endpoint disabled

Ask the administrator to check semantic query and MCP enablement.

Unknown profile

Check the selected database and semantic_catalog.

Invalid arguments

Compare the submitted object with that tool’s inputSchema.

Missing concept or ambiguous interpretation

Review the profile bindings or answer the clarification before retrying.

Permission denied

Use a credential authorized for the profile and operation; changing the JSON actor name does not grant access.

See MCP Tools for tool families and Results And Inspection for interpreting answers.