Tribal MCP Server

How to use

You integrate Tribal with an MCP client to store new errors, look up similar problems, and retrieve solutions. Use the HTTP MCP interface when you want to connect to a remote Tribal instance by URL. Use the local, stdio-based interface when you want to run Tribal as a local tool and connect via a command or launch integration. Typical workflows include capturing errors from your editor or IDE, then querying for similar issues to quickly surface relevant fixes.

How to install

Prerequisites: Python 3.12+ and the uv package manager (uv is recommended).

# Option 1: Direct installation with uv
cd /path/to/tribal
uv pip install .

# Option 2: Development installation
cd /path/to/tribal
uv pip install -e .

# Option 3: Build the package first
cd /path/to/tribal
uv pip install build
python -m build
uv pip install dist/tribal-0.1.0-py3-none-any.whl

# Option 4: Using the uv tool install flow
cd /path/to/tribal
uv tool install .
uv tool install -e .

Additional sections

Configuration and runtime behavior are designed for simple, repeatable deployments. You can run Tribal as a local server or expose it via a remote MCP URL for Claude and other MCP clients. The server uses JWT authentication by default and can store data locally in ChromaDB or in AWS S3 when configured.

To verify installation, confirm the Tribal executable is available and check its version.

Running the server can be done in several ways. The core commands you’ll use are shown in the examples below. For local quick start, you can run the Tribal server directly; for production or containerized setups, use the Docker-based workflow.

Configuration and security notes

Environment variables let you customize storage, authentication, and networking. The FastAPI server supports a persistent directory for ChromaDB, an API key for access control, a JWT secret key, and port configuration. The MCP interface exposes its own URL, port, and host settings, and you can optionally enable AWS integration for S3-backed storage.

{
  "mcpServers": {
    "tribal": {
      "command": "tribal",
      "args": []
    }
  }
}

Troubleshooting

If you run into issues, verify the Tribal executable is on your PATH, confirm the MCP server URL or local command, and check logs for error messages. Ensure the database directory exists and has proper permissions. If authentication is failing, verify your API key and JWT secret key are correctly configured.

Notes on deployment and integration

You can run Tribal locally or deploy via Docker Compose. For Claude integration, you can point Claude at the local MCP endpoint or register Tribal as a MCP server using a launch command for local development.

add_error

Create a new error record via POST /errors to store an error with context and solution.

get_error

Retrieve a specific error by UUID via GET /errors/{id}.

update_error

Update an existing error record via PUT /errors/{id} to modify details or solutions.

delete_error

Remove an error record via DELETE /errors/{id}.

search_errors

Query errors by criteria via GET /errors to find matching records.

find_similar

Perform a semantic similarity search via GET /errors/similar to surface related errors.

get_token

Obtain a JWT token via POST /token for authenticated requests.