Blawx

You can run a lightweight, local MCP server that talks to the Blawx API using your Blawx API key. This server serves an SSE endpoint over HTTP and lets your coding agent discover project content, ask questions, and review answers against your Blawx project without deploying a full backend.

How to use

To use this MCP server, start it locally and connect your MCP client or editor with the provided SSE endpoint. The server fetches data from Blawx using your API key and exposes endpoints that your agent can discover project content, pose questions, and retrieve explanations and model parts. You will typically run the server once, configure your MCP client to point at the local SSE URL, and then perform actions such as listing questions, asking questions with facts, and reviewing answers.

How to install

Prerequisites: Python 3.10+

From the repository root, install the package in editable mode and set up the environment variables before running the server.

python -m pip install -e .

Additional configuration and notes

Configure the following environment variables before starting the server. These values tell the MCP server how to reach your Blawx project and what credentials to use.

export BLAWX_API_KEY="your_key_here"
export BLAWX_TEAM_SLUG="your_team_slug"
export BLAWX_PROJECT_ID="42"

Run the MCP server

Run the server from the repository folder. Use the Python interpreter from the local virtual environment to execute the MCP module.

./.venv/bin/python -m blawx_mcp

Optional bind overrides

If you need a different network binding, set the host and port environment variables before starting the server.

export BLAWX_MCP_HOST="127.0.0.1"
export BLAWX_MCP_PORT="8765"

Connect to Your Coding Agent

Configure your MCP client with the local SSE URL. The typical tool definition points to the SSE endpoint at http://127.0.0.1:8765/sse.

{
  "servers": {
    "my-blawx-sse-server": {
      "url": "http://127.0.0.1:8765/sse",
      "type": "http"
    }
  },
  "inputs": []
}

Available tools

blawx_health

Verify the Blawx app is reachable and returns a health status.

blawx_questions_list

List shared questions available in the project.

blawx_question_detail

Retrieve details for a specific question.

blawx_fact_scenarios_list

List stored fact scenarios to reuse facts.

blawx_fact_scenario_detail

Show the facts contained in a specific fact scenario.

blawx_ontology_list

List ontology categories and relationships.

blawx_ontology_category_detail

Details for a specific ontology category.

blawx_ontology_relationship_detail

Details for a specific ontology relationship, including arity and parameters.

blawx_question_ask_with_fact_scenario

Ask a question using a stored fact scenario.

blawx_question_ask_with_facts

Ask a question using an explicit facts payload.

blawx_list_answers

Get the list of answers and their bindings for a question.

blawx_list_explanations

Get the list of explanations available for a specific answer.

blawx_get_model_part

Retrieve the answer set part of an explanation.

blawx_get_attributes_part

Retrieve the attributes (constraints) part of an explanation.

blawx_get_explanation_part

Retrieve a tree-structured explanation for an answer.

blawx_get_constraint_satisfaction_part

Retrieve the constraint satisfaction details for an explanation.