FlowMCP is a Tool Catalog with pre-built API templates and a Knowledge Base for API workflows. It unifies access to APIs through two equal channels: CLI (direct access) and MCP/A2A Server (for agents and MCP clients). This repository contains the specification documents and reference examples — no executable code.
FlowMCP organizes its catalog in three levels:
flowchart TD
R[Root Level — Shared]
R --> P[Provider Level]
R --> AG[Agent Level]
subgraph Root
SL[Shared Lists]
SH[Shared Helpers]
REG[registry.json]
end
subgraph Providers
P1[etherscan/ — tools, resources, prompts]
P2[coingecko/ — tools, resources, prompts]
end
subgraph Agents
A1[crypto-research — manifest + prompts]
A2[defi-monitor — manifest + prompts]
end
R --> Root
P --> Providers
AG --> Agents
Root holds shared lists, helpers, and the catalog manifest. Providers wrap APIs with deterministic tools. Agents compose tools from multiple providers for specific tasks.
| Feature | Description |
|---|---|
| Agents | Groups evolve into full agent manifests with model binding, system prompts, tests, and tool cherry-picking |
| Prompt Architecture | Two-tier system: Provider-Prompts (model-neutral) + Agent-Prompts (model-specific with testedWith) |
| Catalog | Named directory with registry.json manifest. Multiple catalogs coexist independently |
| ID Schema | Unified namespace/type/name format for referencing tools, resources, and prompts |
| Placeholder Syntax | {{type:name}} for prompt/skill content — {{tool:x}}, {{input:x}}, {{resource:x}}, {{skill:x}} |
| Test Minimum | Increased from 1 to 3 per tool, resource query, and agent |
| Agent Tests | expectedTools (deterministic) + expectedContent (assertions) |
| Three-Level Architecture | Root (shared) → Provider (one API per namespace) → Agent (compositions) |
git clone https://github.com/flowmcp/flowmcp-spec.git
cd flowmcp-specA minimal v3.0.0 schema:
export const main = {
namespace: 'coingecko',
name: 'Ping',
description: 'Check CoinGecko API server status',
version: '3.0.0',
root: 'https://api.coingecko.com/api/v3',
requiredServerParams: [],
requiredLibraries: [],
tools: {
ping: {
method: 'GET',
path: '/ping',
description: 'Check if CoinGecko API is online',
parameters: [],
tests: [
{ _description: 'Basic health check', },
{ _description: 'Verify response format', },
{ _description: 'Confirm uptime', }
],
output: {
mimeType: 'application/json',
schema: {
type: 'object',
properties: {
gecko_says: { type: 'string' }
}
}
}
}
}
}| # | Document | Description |
|---|---|---|
| 00 | Overview | Vision, three-level architecture, LLM-First philosophy, terminology |
| 01 | Schema Format | main + handlers structure, tool definitions, naming conventions |
| 02 | Parameters | Position/z blocks, shared list interpolation, {{type:name}} placeholder syntax |
| 03 | Shared Lists | Reusable value lists, dependencies, filtering, registry |
| 04 | Output Schema | Output definitions, MIME-Types, response envelope |
| 05 | Security | Zero-import policy, library allowlist, static scan |
| 06 | Agents | Agent manifests, model binding, system prompts, tool cherry-picking |
| 07 | Tasks | MCP Tasks async fields (reserved) |
| 08 | Migration | v1.2.0 → v2.0.0 → v3.0.0 migration guides |
| 09 | Validation Rules | Complete validation checklist across all categories |
| 10 | Tests | Tool tests, resource tests, agent tests, response capture |
| 11 | Preload | Schema initialization with startup data |
| 12 | Prompt Architecture | Provider-Prompts, Agent-Prompts, composable references |
| 13 | Resources | SQLite resources, queries, parameter binding |
| 14 | Skills | Skill .mjs format, placeholders, versioning |
| 15 | Catalog | Catalog manifest, registry.json, import flow |
| 16 | ID Schema | Unified namespace/type/name format |
The complete specification is available as a single concatenated file for LLM consumption:
- spec/v3.0.0/llms.txt — All 17 spec documents in one file
This file is auto-generated by a GitHub Action whenever spec files change.
| File | Description |
|---|---|
| Agent Manifest | Complete agent with export const main, tool cherry-picking, tests |
| Agent-Skill | Model-specific skill with testedWith and {{tool:x}} references |
| Provider-Prompt | Model-neutral prompt scoped to one namespace |
| Registry | Sample catalog manifest with schemas and agents |
- Deterministic over clever — Same input always produces same API call
- Declare over code — Maximize the
mainblock, minimize handlers - Inject over import — Schemas receive data through dependency injection, never import
- Hash over trust — Integrity verification through SHA-256 hashes
- Constrain over permit — Security by default, explicit opt-in for capabilities
| Repository | Description |
|---|---|
| flowmcp-core | Core framework — Schema validation, Agent manifest loading, Tool execution |
| flowmcp-cli | CLI — Search, activate, and run tools and agents |
| flowmcp-schemas | Schema Library — 370+ API schemas, community catalog, agent definitions |
| mcp-agent-server | Agent Server — Deploy FlowMCP agents as MCP/A2A servers |
Contributions welcome. For spec changes, open an issue first to discuss the proposed change.
MIT