How do I use folio-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@folio-mcp search for concepts related to contract law" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

folio-mcp

by alea-institute

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

folio-mcp

MCP server for FOLIO, the Federated Open Legal Information Ontology.

FOLIO is an open-source legal ontology with 18,000+ concepts covering areas of law, document types, legal entities, governmental bodies, and more. This MCP server makes the full ontology available to AI agents as searchable, browsable tools.

A public REST API is already available at https://folio.openlegalstandard.org/ with interactive Swagger documentation at /docs. This MCP server wraps the same ontology for native use in AI coding assistants and agent frameworks.

License: MIT (server code) / CC-BY 4.0 (ontology data)

Backends

folio-mcp supports two interchangeable backends:

Mode	Startup	Dependencies	Use case
API (default)	Instant	`httpx` only	Normal usage — calls the public FOLIO REST API
Local (`--local`)	~10s	`folio-python[search]`	Offline use or when mounting inside folio-api

API mode (default)

The server starts instantly and delegates all queries to the public API at https://folio.openlegalstandard.org/. No local ontology loading required.

Local mode

Loads the full FOLIO ontology in-process (~18k classes). Useful for offline work or when embedded in folio-api.

# Install with local dependencies
pip install folio-mcp[local]

# Run in local mode
folio-mcp --local

# Or via environment variable
FOLIO_MCP_LOCAL=1 folio-mcp

Custom API URL

Point to a different FOLIO API instance:

folio-mcp --api-url https://my-folio-instance.example.com

Related MCP server: Legal Court MCP Server

Installation

Claude Code

claude mcp add folio -- uvx folio-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "folio": {
      "command": "uvx",
      "args": ["folio-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "folio": {
      "command": "uvx",
      "args": ["folio-mcp"]
    }
  }
}

VS Code

Add to your User Settings (JSON):

{
  "mcp": {
    "servers": {
      "folio": {
        "command": "uvx",
        "args": ["folio-mcp"]
      }
    }
  }
}

Remote (Streamable HTTP)

Connect to the hosted endpoint:

https://folio.openlegalstandard.org/mcp

Manual (pip)

pip install folio-mcp
folio-mcp

Tools (12)

Tool	Description
`search_concepts(query, limit=10)`	Search concepts by label/name using fuzzy matching
`search_definitions(query, limit=10)`	Search concepts by definition text
`query_concepts(...)`	Advanced query with composable text and structural filters
`query_properties(...)`	Query OWL object properties by label, domain, range
`get_concept(iri)`	Get full details for a concept by IRI
`export_concept(iri, format)`	Export a concept as markdown, JSON-LD, or OWL XML
`list_branches()`	List all 24 taxonomy branches with concept counts
`get_taxonomy_branch(branch_name, max_depth)`	Get concepts in a taxonomy branch
`get_children(iri, max_depth)`	Get child concepts
`get_parents(iri, max_depth)`	Get parent concepts
`get_properties()`	Get all OWL object properties (relationships)
`find_connections(subject_iri, property_name, object_iri)`	Find semantic triples

Browse operations return compact summaries (iri, label, definition). Use get_concept(iri) for full details including translations (31% of concepts, 10+ languages), preferred labels, external identifiers, and cross-references.

Prompts (3)

Prompt	Description	Argument
`classify-document`	Classify a legal document against the FOLIO taxonomy	`description`
`identify-area-of-law`	Identify applicable areas of law for a situation	`situation`
`classify-entity`	Classify a legal entity (person, org, role)	`entity`

Each prompt guides the LLM through the correct tool workflow and returns structured output (FOLIO label, IRI, definition, confidence, reasoning).

Resources (3)

Resource URI	Description
`folio://branches`	Branch names with concept counts (564 bytes)
`folio://stats`	Ontology statistics — version, class/property counts, license
`folio://branch/{name}`	Top-level concepts in a specific branch (on-demand)

Taxonomy Branches

The FOLIO ontology is organized into 24 top-level branches:

Branch	Description
`actors_players`	Parties, roles, and participants in legal matters
`areas_of_law`	Legal practice areas and specializations
`asset_types`	Types of assets (real property, intellectual property, etc.)
`communication_modalities`	Communication channels and methods
`currencies`	Monetary currencies
`data_formats`	Data and file formats
`document_artifacts`	Legal documents, contracts, filings
`engagement_terms`	Terms of engagement and fee arrangements
`events`	Legal events and milestones
`forum_venues`	Courts, tribunals, and dispute resolution venues
`governmental_bodies`	Government agencies and departments
`industries`	Industry sectors and classifications
`languages`	Natural languages
`folio_types`	FOLIO internal type classifications
`legal_authorities`	Statutes, regulations, case law
`legal_entities`	Entity types (corporations, LLCs, trusts, etc.)
`locations`	Geographic locations and jurisdictions
`matter_narratives`	Matter descriptions and narratives
`matter_narrative_formats`	Formats for matter narratives
`objectives`	Legal objectives and goals
`services`	Legal services and service types
`standards_compatibilities`	Standards and compatibility mappings
`statuses`	Status values for matters, documents, etc.
`system_identifiers`	System and external identifiers

Development

# Clone and install
git clone https://github.com/alea-institute/folio-mcp.git
cd folio-mcp
uv sync

# Run tests (requires folio-python for local backend tests)
uv sync --extra local
uv run pytest tests/

# Run with MCP Inspector
uv run mcp dev folio_mcp/server.py

# Run locally for Claude Code
claude mcp add folio-dev -- uv run --directory /path/to/folio-mcp folio-mcp

Available Tools

12 tools

export_conceptA

Export a FOLIO concept in a specific format.

Args: iri: The concept IRI or identifier. format: Output format — "markdown", "jsonld", or "owl_xml".

Returns: The concept in the requested format, or an error message.

Inputs: iri (required), format. Returns: result

find_connectionsA

Find semantic connections (triples) between FOLIO concepts.

Searches for subject-property-object triples. At minimum, provide a subject_iri. Optionally filter by property and/or object.

Args: subject_iri: IRI of the subject concept. property_name: Optional property name or IRI to filter by. object_iri: Optional object concept IRI to filter by.

Returns: JSON array of triples [{subject: {...}, property: {...}, object: {...}}].

Inputs: subject_iri (required), object_iri, property_name. Returns: result

get_childrenA

Get child concepts of a FOLIO concept. Returns compact summaries.

Args: iri: A concept IRI (e.g., "https://folio.openlegalstandard.org/R07tQM...") or short ID (e.g., "R07tQM..."). NOT a branch name — use get_taxonomy_branch for branch names like "areas_of_law". max_depth: Depth limit (default 1 for direct children). Keep at 1-2 to avoid large results.

Returns: JSON array of {iri, label, definition} summaries. Use get_concept(iri) for full details on a specific child.

Inputs: iri (required), max_depth. Returns: result

get_conceptA

Get full details for a specific FOLIO concept by IRI.

Accepts short IDs (e.g., "RSYBzf149Mi5KE0YtmpUmr"), full IRIs (e.g., "https://folio.openlegalstandard.org/RSYBzf149Mi5KE0YtmpUmr"), or partial matches.

Args: iri: The concept IRI or identifier.

Returns: Full JSON representation of the concept, or an error message.

Inputs: iri (required). Returns: result

get_parentsA

Get parent concepts of a FOLIO concept. Returns compact summaries.

Args: iri: A concept IRI (e.g., "https://folio.openlegalstandard.org/R07tQM...") or short ID. NOT a branch name. max_depth: Depth limit (default 1 for direct parents).

Returns: JSON array of {iri, label, definition} summaries. Use get_concept(iri) for full details on a specific parent.

Inputs: iri (required), max_depth. Returns: result

get_propertiesA

Get all OWL object properties defined in the FOLIO ontology.

Returns properties that describe relationships between concepts (e.g., "hasJurisdiction", "appliesTo", "governedBy").

Returns: JSON array of properties with iri, label, definition, domain, and range.

Inputs: no named parameters. Returns: result

get_taxonomy_branchA

Get concepts in a FOLIO taxonomy branch. Returns compact summaries.

Args: branch_name: Branch name (e.g., "areas_of_law", "document_artifacts"). Use list_branches() to see all available branch names. max_depth: Depth limit. Use 1 (default) for top-level only. WARNING: depth >2 can return very large results. Navigate incrementally with get_children() instead.

Returns: JSON array of {iri, label, definition} summaries. Use get_concept(iri) for full details on a specific concept.

Inputs: branch_name (required), max_depth. Returns: result

list_branchesA

List all FOLIO taxonomy branches with concept counts.

Returns the 24 top-level categories of the FOLIO ontology (e.g., areas_of_law, document_artifacts, legal_entities).

Returns: JSON object mapping branch names to concept counts.

Inputs: no named parameters. Returns: result

query_conceptsA

Query FOLIO concepts with composable text and structural filters.

More powerful than search_concepts — supports field-specific matching, structural constraints, and multiple match modes. All specified filters must match (AND logic).

Text filters: label: Match against the concept's primary label (rdfs:label). definition: Match against the concept's definition (skos:definition). alt_label: Match against alternative labels (skos:altLabel). example: Match against examples (skos:example). any_text: Match against ALL text fields (label, definition, alt_labels, examples, notes, comment).

Structural filters: branch: Limit to a taxonomy branch (e.g., "AREA_OF_LAW", "CURRENCY", "LEGAL_ENTITY"). parent_iri: Only descendants of this IRI (transitive subClassOf). has_children: True = non-leaf concepts only, False = leaf concepts only. deprecated: Include deprecated concepts (default False). country: Match against the country field.

Control: match_mode: "substring" (default), "exact", "regex", or "fuzzy". limit: Maximum results (default 20).

Returns: JSON array of matching concepts.

Inputs: label, limit, branch, country, +8 more. Returns: result

query_propertiesA

Query FOLIO object properties with composable text and structural filters.

Replaces get_properties() when you need filtered results instead of the full list.

Text filters: label: Match against property label (e.g., "jurisdiction", "applies"). definition: Match against property definition.

Structural filters: domain_iri: Only properties whose domain includes this class IRI. range_iri: Only properties whose range includes this class IRI. has_inverse: True = only properties with inverses, False = only without.

Control: match_mode: "substring" (default), "exact", "regex", or "fuzzy". limit: Maximum results (default 20).

Returns: JSON array of matching properties with iri, label, definition, domain, range.

Inputs: label, limit, range_iri, definition, +3 more. Returns: result

search_conceptsA

Search FOLIO concepts by label (name).

Finds legal concepts whose names match the query using fuzzy matching. Use this as the primary entry point for finding concepts.

Args: query: Search term (e.g., "bankruptcy", "software license", "trust"). limit: Maximum number of results to return (default 10).

Returns: JSON array of matching concepts with iri, label, definition, and score.

Inputs: query (required), limit. Returns: result

search_definitionsA

Search FOLIO concepts by definition text.

Finds legal concepts whose definitions match the query. Use this when searching by name doesn't find what you need.

Args: query: Search term to match against definitions. limit: Maximum number of results to return (default 10).

Returns: JSON array of matching concepts with iri, label, definition, and score.

Inputs: query (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-08-01 19:25 across 12 tools

Disambiguation4/5

Most tools are clearly distinct (list_branches, get_children, get_parents, export_concept, find_connections). Minor overlap exists between search_concepts/search_definitions and the more powerful query_concepts, and between get_properties and query_properties, but descriptions explicitly differentiate their use cases.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (list_, search_, get_, export_, find_, query_). The verbs are appropriate and predictable, making the set easy to navigate.

Tool Count5/5

With 12 tools, the server is well-scoped for ontology exploration. Each tool has a clear role, though query_concepts and query_properties could potentially consolidate some simpler tools, the count is not excessive.

Completeness5/5

The tool surface comprehensively supports read-only exploration of the FOLIO ontology: browsing branches, searching by label/definition, navigating hierarchy, retrieving details, exporting, finding relationships, and querying with filters. No obvious gaps for typical use cases.

Maintenance

ActivityNo data

ResponsivenessOutdated data

Resources

Related MCP Connectors

ORANO MCP Server
io.github.infotik
Read-only MCP server exposing a user ORANO library to their own AI agent.
Note Taking Knowledge & Memory Search
1
https://api.oranoai.com/mcp/
forkast-mcp-docsA
io.github.ForkastPredict
MCP server for querying Forkast documentation
Documentation Access Search Developer Tools
42
https://mcp.forkast.gg/mcp
UnifAPI
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2
https://mcp.unifapi.com
mcpA
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
https://llmse.ai/mcp

Related MCP Servers

agentfolio-mcp-server
Agent Orchestration Blockchain Web3 & Decentralized Tech
0xbrainkid
A
license
A
quality
F
maintenance
MCP server for AgentFolio — the identity and reputation layer for AI agents. Query agent profiles, trust scores, verification status, and marketplace listings through 8 MCP tools.
Updated 8 months ago (2026-03-25 09:09 UTC)
9
128 npm
1
MIT
Legal Court MCP Server
Legal & Compliance Government Data Search
AiAgentKarl
A
license
A
quality
D
maintenance
MCP Server providing AI agents access to over 3 million US court decisions via CourtListener and EU legislation via EUR-Lex, with tools for searching cases, citations, judges, and court information.
Updated 7 months ago (2026-04-03 16:05 UTC)
6
MIT
Vaquill-AI/vaquill-mcpofficial
Legal & Compliance Search Government Data
Vaquill-AI
A
license
A
quality
B
maintenance
MCP server for Vaquill legal research API. Covers US federal + 50-state law (USC, CFR, state legislation, CourtListener case law)
Updated 4 days ago (2026-11-06 19:03 UTC)
25
127 PyPI
9
MIT
mcp-openalex
Research & Data Open Data Search
ELumya
A
license
A
quality
D
maintenance
MCP server for the OpenAlex scholarly database, providing AI agents with tools to search and retrieve academic works, authors, and institutions via natural language queries.
Updated 7 months ago (2026-04-15 12:43 UTC)
8
MIT

folio-mcp

Backends

API mode (default)

Local mode

Custom API URL

Installation

Claude Code

Claude Desktop

Cursor

VS Code

Remote (Streamable HTTP)

Manual (pip)

Tools (12)

Prompts (3)

Resources (3)

Taxonomy Branches

Development

Links

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

agentfolio-mcp-server

Legal Court MCP Server

Vaquill-AI/vaquill-mcpofficial

mcp-openalex