leather MCP server
Commit Oct 23, 2026Runs declarative agents on workstations or servers using scheduled jobs, webhooks, and tool calling via a single Go binary.
Also known as TGPSKI/leather
- Stars
- 17
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 23, 2026
- License
- GPL-3.0
What is leather MCP?
leather runs declarative agents on workstations or servers using scheduled jobs, webhooks, and tool calling via a single Go binary.
Summary generated from the project's README
About leather MCP server
Running declarative agents on workstations, servers, or Raspberry Pi is what leather enables through a single Go binary. This infrastructure allows developers to deploy scheduled jobs, one-shot runs, and webhook-driven workflows without a Python stack or a hosted control plane. It functions as a local runtime that supports tool calling, MCP server integration, and filesystem-based FIFO queues for managing agent tasks.
Users interact with the system using Markdown files for agent definitions and YAML for lifecycle scheduling. The setup requires an LLM endpoint and a model, which can be configured via flags, environment variables, or a config file. It supports the OpenAI Chat Completions API, allowing for local models or cloud-based providers. For advanced monitoring, a built-in DevTools UI provides a session timeline and event inspector to track agent activity and tool usage.
What you can do with it
- 1Build multi-stage agent pipelinesChain multiple agents together using queues to triage and then review specific inputs.
- 2Monitor agent execution flowsUse a visual interface to inspect the causal chain of events and tool calls during a run.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
LEATHER_LLM_API_KEYLEATHER_LLM_ENDPOINTLEATHER_MODEL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletgpski/leather is public and reachablegithub.com/tgpski/leather ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-23github.com/tgpski/leather ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubleather
releases | changelog | pkg.go.dev | leather.sh | pate.sh
Local agent infrastructure in one stdlib-only Go binary.
Leather runs declarative agents on your workstation, server, or Raspberry Pi: scheduled jobs, one-shot runs, webhook-driven workflows, tool calling, and auditable outputs.
No Python stack. No hosted control plane. No broker, telemetry, or dependency pile.
cat > summarizer.agent.md <<'EOF'
---
name: summarizer
---
You are a concise planning assistant. Output bullet points only.
EOF
leather validate --agent-dir .
leather run summarizer.agent.md
See it run
Seventeen demos in examples/, each one make target away.
cp examples/env.example examples/.env
$EDITOR examples/.env
make example-02
make example-06
Measured, not asserted
Two claims carry this project, each with its evidence one click away:
- The runtime doesn't get in the way. The same code path runs a profiled 100-webhook burst — 500 LLM calls, 965K tokens, five fan-out/fan-in stages — end to end in 190s at 6.5% avg host CPU and no measurable IO pressure. Leather isn't the bottleneck; the model is. → examples/11-high-volume-ci
- The runtime is where the accuracy lives. The same frozen 4B model spans 62.4% → 81.6% on a 250-issue gold corpus depending only on the design around it — a 22-arm × 2-rig ablation with paired per-issue verdicts and a measured noise floor. The floor isn't the bare model; it's a bad harness. → findings in plain language: examples/14-sig-triage · every cell and verdict: matrix / verdicts · raw run archives committed — auditable without a GPU
What it does
| Agents | *.agent.md — Markdown front and a system prompt with 0-N turns and variable support. |
| Tools | Skills, toolsets, MCP server support, and shell-mcp (make build-shell-mcp) for turning shell commands into agent tools. |
| Curings | Bind agents to queues for flexible multi-stage routing. |
| Queues | Filesystem FIFO — configurable depth, backpressure, concurrency, dead-letter routing, and single-use parameterized queues. |
| Workers | Goroutines with hooks into queues. |
| Tannery | Pipelines connecting agents, curings, workers, and artifacts, with fan-in / fan-out routing. |
| DevTools | Stdlib-JS UI with session timeline, event inspector, curing flow diagram, and live SSE. |
| Notifications | Telegram and Signal backends. |
Build one
A complete agent:
---
name: summarizer
---
You are a concise planning assistant. Output bullet points only.
A schedule for it (*.lifecycle.yaml, optional):
agent: summarizer
schedule: "0 9 * * *"
model: llama3
prompt: Summarize the three most important things to do today.
Run it:
leather validate # check everything parses
leather run ~/.leather/agents/summarizer.agent.md # run once
leather serve --pretty --stats # run on schedule
Chaining two agents behind a webhook — one triages, one reviews, an artifact comes out the other end — is the same primitives composed: see the GUIDE.md: two-agent pipeline recipe and examples/06-multi-agent-curing.
Install
From source:
git clone https://github.com/TGPSKI/leather
cd leather
make build && make build-shell-mcp
make install
With go install:
go install github.com/TGPSKI/leather/cmd/leather@latest
go install github.com/TGPSKI/leather/cmd/shell-mcp@latest
Verify the install — no LLM endpoint required:
leather --version # prints version
make example-01 # runs a mock-LLM example end-to-end
Model and endpoint
Every command above needs a model and an LLM endpoint from somewhere. All
three forms set the same values — flag wins over env var, env var wins over
config.yaml:
# flag
leather run agent.md --model llama3 --llm-endpoint http://localhost:11434
# env var
export LEATHER_MODEL=llama3
export LEATHER_LLM_ENDPOINT=http://localhost:11434
# config.yaml
model: llama3
llm_endpoint: http://localhost:11434
leather speaks the OpenAI Chat Completions API, so cloud endpoints work the
same way. The bearer token resolves inline value → pass → env var, in that
order:
export LEATHER_LLM_API_KEY="sk-..."
leather serve --llm-endpoint https://api.openai.com --model gpt-4o-mini
# config.yaml + unix pass
llm_endpoint: https://api.openai.com
model: gpt-4o-mini
llm_api_key:
pass: openai/api-key # `pass show openai/api-key`
env: OPENAI_API_KEY # fallback when pass is empty or unavailable
Go deeper
Pick your path by the question you're asking; each row starts approachable and descends as far as you want to go.
| you want to… | start here | then |
|---|---|---|
| build an agent, pipeline, or tool | docs/GUIDE.md — every file format, plus a recipe for each pattern above | examples/ (17 runnable demos) · docs/CONVENTIONS.md (env-var reference) · docs/TEMPLATES.md |
| check the claims above | examples/14-sig-triage — findings in plain language | matrix / verdicts → experiment design → claim ledger → raw archives |
| see a real deployment | docs/REFERENCE-TANNERY.md — six agents, four queues, running unattended, with measured run records and an honest A/B against a frontier control | the system itself: TGPSKI/catnip/tannery |
| understand the internals | docs/ARCHITECTURE.md — package layout and data flow | docs/modules/ (per-package) · docs/GLOSSARY.md |
| contribute (human or agent) | AGENTS.md — the routing table | .subagents/ domain guides · CHANGELOG.md |
History
| Date | Event |
|---|---|
| 2026-05-21 | Repository created |
| 2026-06-01 | v0.1.0 "napa", first public release; c09d184 is the first commit in this history |
| 2026-06-05 | v0.2.0 "weathered" |
| 2026-07-05 | v0.4.0 "vegan leather" |
| 2026-07-29 | v0.5.0 "alligator": examples/14-sig-triage and its eval campaign |
| 2026-08-09 | v0.5.3; docs/REFERENCE-TANNERY.md |
| 2026-09-07 | v0.5.4; releases archived on Zenodo from this version on, concept DOI 10.5281/zenodo.22637735 |
leather MCP questions
What are the system requirements for leather?
It is a single Go binary that requires no Python stack, no hosted control plane, and no external broker or telemetry dependencies.
How do I configure the LLM endpoint and model?
You can set the model and endpoint using command line flags, environment variables, or a config.yaml file.