Noctua

You can use the noctua-mcp server to edit GO-CAM models through the Barista API using a streamlined MCP interface. It acts as a thin wrapper around the noctua-py library, exposing GO-CAM editing capabilities in a consistent, tool-accessible way for MCP clients.

How to use

You connect an MCP client (such as Claude Code or Claude Desktop) to the noctua-mcp server. The server accepts credentials from the client and uses them to authorize actions against Barista. Practical capabilities include adding GO-CAM entities and relations, attaching evidence, and querying model summaries. You interact with the server through your MCP client’s standard workflow, enabling GO-CAM editing with familiar MCP tools.

How to install

Prerequisites you need before installation:

• A compatible runtime for stdio-based MCP servers (the server is designed to be run as a local stdio process).
• Access to the Barista API with a valid token to authenticate requests.

uvx noctua-mcp

# For development
uv run noctua-mcp serve

# Running in a container (example)
docker run -e BARISTA_TOKEN="your-token" noctua-mcp

Configuration and environment

Credentials are provided by your MCP client at runtime and passed to the server when it starts. This keeps user credentials private and scoped per session.

Environment variables you will use:

• BARISTA_TOKEN: Barista API token (required)
• BARISTA_BASE: Barista server URL (default: http://barista-dev.berkeleybop.org)
• BARISTA_NAMESPACE: Minerva namespace (default: minerva_public_dev)
• BARISTA_PROVIDED_BY: Provided-by agent (default: http://geneontology.org)

If you deploy via smithery.ai, the setup will define how credentials are provided to the server and may pass the BARISTA_TOKEN at startup. The smithery.yaml configuration enables stdio-based MCP communication and allows you to override Barista endpoints and namespace if needed.

Runtime configuration via MCP client

Your MCP client config should specify how to start the server and how credentials are passed. An example approach is to configure the server to run as a stdio process, with the client supplying the BARISTA_TOKEN at startup.

Troubleshooting and tips

• Ensure BARISTA_TOKEN is provided by the MCP client at startup; the server prints no secrets in outputs.
• Verify that the Barista base URL and namespace are set correctly if you use non-default environments.
• If the server cannot connect to Barista, double-check network access and the provided token scope.

Notes on deployment options

The server supports both local stdio-based operation and cloud deployments that pass credentials from the MCP client. When deployed in containers or via cloud configurations, maintain secure handling of BARISTA_TOKEN and avoid echoing credentials in logs.

Available tools

add_individual

Add an instance of a GO/ECO term to a GO-CAM model.

add_fact

Create a relation between two GO-CAM entities by specifying subject, object, and predicate.

add_evidence_to_fact

Attach evidence to an existing fact with ECO and optional sources.

remove_individual

Remove an individual from the GO-CAM model.

remove_fact

Remove a relation between two entities.

add_basic_pathway

Add a basic GO-CAM unit with pathway and activity annotations.

add_causal_chain

Link activities causally to form a chain of events.

get_model

Retrieve the full model JSON for a given model_id.

model_summary

Get statistics and a summary for a given model_id.

configure_token

Set the Barista token at runtime (not echoed).