mcp server

brainkb

MCP server for querying BrainKB, a knowledge base for neuroscience knowledge graphs.

Description as published by the maintainer. Source

• version 0.1.0
• active
• memory and context

active — Registry entry last updated 2026-07-23. Dashed tags are derived by ZBS Index from the published description, not stated by the maintainer.

What this server can do

53 functions, named and described by the server itself. Parameter names are shown because they say more about what a function does than its name usually does.

brainkb_activate_user(email)

(Admin) Activate a user's account (sets the JWT user active) by email. Required: email.

brainkb_add_access_rule(slug, action, subject_type, subject_value)

(Space manager) Restrict a space action to a subject. action: 'read' | 'write' | 'manage'. subject_type: 'global_role' (e.g. 'Admin','Lab Member') | 'member' (an email) | 'space_role' ('viewer'|'editor'|'owner', matched as >=). When rules exist for an action, only matching callers may perform it; the space owner and Admin/SuperAdmin always bypass (no lockout). Example: restrict writing to Admins -> action='write', subject_type='global_role', subject_value='Admin'. Required: slug, action, subject_type, subject_value.

brainkb_add_space_graph(slug, description, named_graph_iri)

Register a named graph and bind it to a space, so ingest/read on that graph are governed by the space's membership and visibility. Owner/editor only. The named_graph_iri is **globally unique** — one graph belongs to exactly one space. If it's already registered (to any space) the call returns 409; graph bindings are permanent (no unregister/delete). Required: slug, named_graph_iri.

brainkb_add_space_member(role, slug, member_email)

Add/update a space member. role: 'owner' | 'editor' | 'viewer'. Owner only. Required: slug, member_email.

brainkb_assign_role(role, email)

(Admin) Assign a role/group to a user by email (e.g. 'Lab Member', 'External', or a custom group). The user must already have a profile (created on first login/registration). NOTE: assigning the 'Admin'/'SuperAdmin' role is SuperAdmin-only (hierarchy: SuperAdmin > Admin). Required: email, role.

brainkb_available_roles

(Admin) List the available roles/groups (Admin, Lab Member, Curator, …).

brainkb_ban_user(email, reason)

(Admin) Ban a user by email (reversible; preserves history). This is how accounts are removed — there is NO hard delete. Banning an Admin is SuperAdmin-only; SuperAdmin accounts cannot be banned. Required: email, reason.

brainkb_capabilities(member)

(Admin only) Show a user's roles, effective capabilities, and delegated grants. Useful to check why someone can/can't create team spaces, ingest, etc. Required: member.

brainkb_create_permission(name, action, resource, description)

(Admin) Create a new usermanagement permission, e.g. name='dataset.export', resource='dataset', action='export'. Attach it to roles via the usermanagement role-permissions API. Required: name, resource, action.

brainkb_create_role(name, category, description)

(Admin) Create a new role/group — e.g. an 'External' collaborator group — which can then be assigned with brainkb_assign_role. Required: name.

brainkb_create_space(name, slug, space_type, visibility, description)

Create a workspace/space. The caller becomes owner. slug: lowercase/hyphen id, **globally unique** — if it's already taken the call returns 409 (pick another slug; slugs are never reused/deleted). visibility: 'private' or 'public'; description: short human description (recommended — surfaces in the registry); space_type: 'individual' (a personal space — any write-capable role) or 'team' (a shared space — only Admin/SuperAdmin, or a user granted create_team_space). Required: slug, name.

brainkb_create_token(days, name)

Generate a Personal Access Token (PAT) for browser-free auth. Requires you to be logged in already (brainkb_login or brainkb_globus_login). The token is shown ONCE and never again — copy it and set it as BRAINKB_TOKEN in your MCP/skill config; then no login or browser is needed until it expires. `name`: a label so you can tell tokens apart (e.g. 'laptop'). `days`: lifetime (default 90, server-capped). Treat the returned token like a password.

brainkb_deactivate_user(email)

(Admin) Deactivate a user's account by email. Required: email.

brainkb_delta(job_id)

The exact triples a job added (its delta), as JSON-LD. Required: job_id.

brainkb_delta_compare(job_id_a, job_id_b)

Compare two jobs' deltas: A-only / B-only / shared triple counts + triples. Required: job_id_a, job_id_b.

brainkb_delta_history(named_graph_iri)

A named graph's change history: one entry per ingest delta (job, triple count, timestamp), newest first. Required: named_graph_iri.

brainkb_discard_upload(upload_id)

Delete one of your staged uploads without ingesting it. Required: upload_id.

brainkb_finish_login(code, base_url)

Complete an OAuth login started with brainkb_globus_login by exchanging the one-time code shown in the browser for a session token. The code is single-use and never echoed back. Required: code.

brainkb_globus_login(base_url, provider)

Start an OAuth login (Globus / ORCID / GitHub) for THIS session — use this instead of brainkb_login when the user signs in with Globus rather than a password. Returns a URL to open in a browser; after signing in, the page shows a short one-time code — pass it to brainkb_finish_login(code) to complete. (The browser step is unavoidable: only the user can consent at the provider.)

brainkb_grant_capability(member, capability)

(Admin only) Delegate a capability to a user — e.g. 'create_team_space' or 'manage_team_space' so a Curator/Lab Member can create/manage team spaces. Grantable: create_private_space, create_team_space, manage_team_space, ingest, recover, read_private (NOT the admin-only 'grant'/'sparql_admin'). Required: member, capability.

brainkb_grant_role_capability(role, capability)

(Admin only) Grant a capability to a whole role/group so EVERY member gets it — e.g. give a custom group 'uk_collaborator' the 'ingest' or 'create_private_space' capability. Grantable: create_private_space, create_team_space, manage_team_space, ingest, recover, read_private (NOT the admin-only 'grant'/'sparql_admin'). Create the group first with brainkb_create_role, then assign it to users with brainkb_assign_role. Required: role, capability.

brainkb_ingest_files(file_paths, max_concurrency, named_graph_iri)

Ingest local RDF files (ttl/nt/nq/rdf/owl/jsonld/json) into a named graph. Returns a job_id; runs in the background — poll with brainkb_job_status. Required: named_graph_iri, file_paths.

brainkb_ingest_text(data, sha256, expected_bytes, named_graph_iri)

Ingest raw RDF text (Turtle / N-Triples / JSON-LD, auto-detected) into a named graph. Returns a job_id; ingestion runs in the background — poll with brainkb_job_status. The graph must be registered (see brainkb_add_space_graph) and the caller must have write access to its space. `sha256` / `expected_bytes` are an integrity contract, and you should use them whenever the RDF came from a file. Ingest is append-only — no delete for triples, no unregister for a graph — so RDF that arrives here mangled is permanent. Because `data` is a string, it passes through the caller's context, where dense Turtle is exactly what gets silently altered: ligatures, Greek letters, embedded newlines, escaped quotes. Declare the digest of the bytes you MEANT to send (`shasum -a 256 file.ttl`) and this refuses the write on any mismatch, turning an unrecoverable corruption into a clean rejection. Required: named_graph_iri, data.

brainkb_ingest_upload(upload_id, named_graph_iri)

Ingest a file you staged with `POST /upload` into a named graph. This is the route for a large local file: your HTTP client streams the bytes straight to this server over HTTPS, then you name the resulting upload_id here. The server reads its own staged copy and posts it to the ingest API internally, so the RDF never passes through a model's context — nothing to transcribe, no context-window ceiling, and no reason to split the document (splitting breaks blank-node identity and silently detaches triples, permanently). Stage a file with any HTTP client — the point is that the LIBRARY reads the file, so the bytes never pass through a model: import requests, hashlib, pathlib f = pathlib.Path("review.ttl") r = requests.post( "https://mcp.brainkb.org/upload", params={"filename": f.name, "sha256": hashlib.sha256(f.read_bytes()).hexdigest()}, headers={"Authorization": f"Bearer {TOKEN}"}, data=f.open("rb"), # streamed — never loaded into memory ) print(r.json()) # -> {"upload_id": "up_...", "state": "staged"} It returns an upload_id and the sha256 the server computed — compare it with your own before ingesting. Returns a job_id; poll brainkb_job_status, then reconcile brainkb_delta(job_id) against the triple count you expected. The staged copy is deleted once the ingest API has accepted the bytes. Required: named_graph_iri, upload_id.

brainkb_job_status(job_id)

Detailed status of one ingest job: status, progress %, current file/stage, per-file failures, and (when complete) a summary. Required: job_id.

brainkb_list_access_rules(slug)

List a space's fine-grained access rules (member/manager of the space). Required: slug.

brainkb_list_capabilities

(Admin only) Catalog of all KG capabilities, which are delegatable ('grantable'), which are admin-only, and a description of each. Use this to see the available permission options before granting to a user or group/role.

brainkb_list_jobs(limit)

List the user's ingest jobs (newest first) with status and progress.

brainkb_list_permissions

(Admin) List all usermanagement permissions (resource/action pairs used for page-access and role-permission mapping). These are the addable 'permission' options; KG action-capabilities are listed by brainkb_list_capabilities.

brainkb_list_registered_graphs

List registered named graphs visible to the caller (private-space graphs the caller can't access are hidden).

brainkb_list_spaces

List spaces the user can see (their own/member spaces + public ones), each annotated with THIS caller's permission so you know what they may do: - your_role: 'owner' | 'editor' | 'viewer' | null (their space membership) - is_owner: they own the space - access: 'owner' | 'member' | 'public' (how it's available to them) - can_write: their space role permits ingest (owner/editor) — a real ingest also needs the 'ingest' capability + any per-space access rules. Use this to tell the user which spaces they can read vs. write vs. only see as public.

brainkb_list_tokens

List your Personal Access Tokens (metadata only — the secret is never shown): id, name, prefix, created/last-used/expiry, and whether each is active/revoked/expired. Use the id with brainkb_revoke_token.

brainkb_list_uploads

List RDF files YOU have staged with POST /upload but not yet ingested. Shows each upload_id, its size, sha256 and when it expires. Only your own uploads are visible.

brainkb_list_users(q, role, limit)

(Admin) List users (profiles) — filter by `q` (name/email/orcid) or `role`. Shows profile_id, email, roles, providers, ban status.

brainkb_login(email, base_url, password)

Authenticate to BrainKB with the user's credentials and cache the JWT for THIS session only (isolated per caller). The password/token are never echoed. Uses single sign-on: one login mints a refresh token, cached for THIS session, which is exchanged on demand for per-service access tokens (query_service, usermanagement, …). Falls back to a legacy per-service token if the backend has no SSO. On the hosted multi-user remote you can skip this and instead have your client send an 'Authorization: Bearer <token>' header (a refresh token unlocks all services). Required: email, password.

brainkb_logout

Forget the cached token for this session.

brainkb_provenance_graph(named_graph_iri)

PROV-O ingestion/activity history (JSON-LD) for a named graph. Required: named_graph_iri.

brainkb_provenance_job(job_id)

PROV-O provenance bundle (JSON-LD) for one ingest job. Required: job_id.

brainkb_read_space(slug)

Read all RDF (JSON-LD) in a space's graphs. Public spaces are readable by anyone; private spaces require membership. Required: slug.

brainkb_recover_job(job_id)

Attempt to recover a stuck/errored ingest job (marks it recoverable/errored). Required: job_id.

brainkb_remove_access_rule(slug, rule_id)

(Space manager) Delete a fine-grained access rule by its id (see brainkb_list_access_rules). Required: slug, rule_id.

brainkb_remove_role(role, email)

(Admin) Remove a role/group from a user by email. Required: email, role.

brainkb_revoke_capability(member, capability)

(Admin only) Revoke a previously granted capability from a user. Required: member, capability.

brainkb_revoke_role_capability(role, capability)

(Admin only) Revoke a capability from a role/group. Required: role, capability.

brainkb_revoke_token(token_id)

Revoke one of your Personal Access Tokens by id (see brainkb_list_tokens). Takes effect immediately — the next call using that token fails. Required: token_id.

brainkb_role_capabilities(role)

(Admin only) List the capabilities granted to a role/group (e.g. 'uk_collaborator', 'Lab Member'). Required: role.

brainkb_search(q, limit, space, offset)

Full-text search over the knowledge graphs, access-filtered by space visibility. Pass `space` to scope to one workspace, omit for a full search. Anonymous/other users never see private-space data. Required: q.

brainkb_set_space_visibility(slug, visibility)

Set a space 'public' (anyone, even anonymous, can read) or 'private' (members only). Owner only. Required: slug, visibility.

brainkb_sparql(sparql_query)

Run an arbitrary SPARQL query. Requires an Admin/SuperAdmin role (the sparql_admin capability) — for ordinary questions prefer brainkb_search, brainkb_read_space, or the provenance/delta tools, which need no admin role. Required: sparql_query.

brainkb_unban_user(email)

(Admin) Lift a ban on a user by email. Required: email.

brainkb_upload_status(upload_id)

State of one of your staged/submitted uploads. `state` is `staged` (waiting for brainkb_ingest_upload), `submitting` (the server is streaming it to the ingest API), `submitted` (accepted — `job_id` is set, poll brainkb_job_status) or `failed` (the staged bytes were KEPT, so retry with brainkb_ingest_upload rather than re-uploading). Required: upload_id.

brainkb_use_token(token, base_url)

Use a Personal Access Token (brainkb_pat_...) for THIS session — an alternative to setting BRAINKB_TOKEN in the config. Validates the token, then caches it so subsequent calls authenticate with it. The token is never echoed. Required: token.

brainkb_whoami

Report the current caller's auth state (email, authenticated, and when the cached session expires). When signed in it also returns base_url — the backend THIS SERVER talks to, which on a hosted deployment is an internal address and says nothing about the caller's own machine.

Last successful function declaration observed on 2026-08-13. Source: https://mcp.brainkb.org/mcp. We list what the server declared; we do not call any of these functions.

Endpoint status observed on 2026-08-13. Source: https://mcp.brainkb.org/mcp.

Signals

These are separate measurements of different things. They are deliberately not combined into one score, because a popularity number that mixes website traffic with saves and stars cannot be checked or acted on.

Where to get it

• Repository — https://github.com/sensein/BrainKB
• Remote endpoint (streamable-http) — https://mcp.brainkb.org/mcp