blawx-mcp

A minimal run-local MCP server (SSE over HTTP) that calls the Blawx API using a Blawx API key.

Prereqs

• Python 3.10+

Install

From this repo root:

python -m pip install -e .

Configuration

Set required configuration in your environment:

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

You will find the Blawx Project ID and team slug in the URL of your web browser when you go to the home page for your project. The pattern will be https://app.blawx.dev/a/{team_slug}/project/{project_id}

You can create a Blawx API Key if you have a Pro subscription to Blawx. Click on "Profile" in the left navigation bar, and find the "Add API Key" button. When you click the button your API key will be displayed only once at the top of the screen. Copy and paste it into your environment settings.

Run

Run the MCP server from this folder (no install required):

./.venv/bin/python -m blawx_mcp

Defaults:

• Binds to 127.0.0.1:8765
• SSE endpoint at http://127.0.0.1:8765/sse

Optional server bind overrides:

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

Connect to Your Coding Agent

Coding agents differ in how they configure MCP servers. This is a typical tool definition in your mcp.json for VS Code.

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

Tools

These tools give your coding agent the following capabilities:

1. Discover what the project exposes (questions, fact scenarios, ontology).
2. Ask a question (using either a stored fact scenario or a custom facts payload).
3. Browse answers and drill into explanations (model/attributes/explanation text).

Here's a brief run-down of the available tools.

Health check

• blawx_health: verifies the Blawx app is reachable and returns status/body.

Discover Project Content

Agents will usually start by listing the available questions, fact scenarios, and vocabulary.

• blawx_questions_list: lists shared questions available in the project.
• blawx_question_detail: retrieves a specific question's details (useful when deciding which question id to ask).
• blawx_fact_scenarios_list: lists stored fact scenarios (prebuilt sets of facts you can re-use).
• blawx_fact_scenario_detail: shows the facts contained in a specific fact scenario.
• blawx_ontology_list: lists ontology categories/relationships (the project's vocabulary).
• blawx_ontology_category_detail: details for a specific category.
• blawx_ontology_relationship_detail: details for a specific relationship (including arity/parameters).

Ask Questions

• blawx_question_ask_with_fact_scenario: asks a question using a stored fact scenario.
• blawx_question_ask_with_facts: asks a question using an explicit facts payload generated by your agent based on your instructions.

NB: It's not clear how good agents will be at generating representations of complicated fact scenarios in complicated vocabularies. It can be helpful to review how your agent formulated your fact scenario if you get unexpected results, and to give it hints on how to do better.

When you pose a question, the answer is saved on the Blawx server for approximately 30 minutes, and your agent can review it over that period of time. Once the data expires, your agent will need to pose the qestion again to analyse the responses further. Based on the instructions provided by the MCP server, it should know to do that when and if required.

Review Answers

Blawx's answers can be quite large, and agents have a limited context window, so the process of reviewing answers is broken into multiple steps.

1. Get the list of answers to the question.
2. Get the list of explanations for a specific answer.
3. Look at the parts of a specific explanation.

• blawx_list_answers: gives the list of answers available, and the bindings in those answers.

• blawx_list_explanations: gives the list of explanations available for an answer

There are four tools to retrieve specific parts of an explanation. These tools all allow the agent to select the entire part, or if it is too long, to select only certain lines at a time.

• blawx_get_model_part: this returns the answer set
• blawx_get_attributes_part: this returns the constraints applied to variables in the model and explanations
• blawx_get_explanation_part: this is the tree-structured, human-readable explanation for the answer
• blawx_get_constraint_satisfaction_part: this is the portion of the explanation that shows how global constraints were satisfied. This is often both verbose and unhelpful, so it is separated out. You may need to ask your agent to seek it specifically if you know your encoding uses constraints and you need to know how they are satisfied.

NB: The other three parts should be read alongisde the attributes, or relevant information may be missing. This instruction is provided to the agent, but if it isn't followed your agent may draw incorrect conclusions. It may be wise to instruct your agent to check the attributes in addition to the other parts of an explanation.

Development

The Blawx server used can be overridden for local development

• BLAWX_BASE_URL (default: https://app.blawx.dev)