Yada MCP server
Commit Nov 8, 2026An AI agent harness for TypeScript backends that executes tool loops using any model, MCP servers, or business databases.
Also known as edgar4/yada
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- MIT
What is Yada MCP?
Yada is an AI agent harness for TypeScript backends that executes tool loops using any model, MCP servers, or business databases.
Summary generated from the project's README
About Yada MCP server
TypeScript backend developers can use Yada to build AI agent applications that execute complex tool loops. It acts as a harness that connects various large language models, including Anthropic, OpenAI, Gemini, and DeepSeek, to your existing business logic. By integrating with MCP servers via stdio or HTTP, HTTP APIs, and business databases, it allows agents to interact with real-world data and systems.
This framework prioritizes safety and reliability by requiring explicit approval for write actions and maintaining durable receipts. It is designed to be resilient, using SQLite, PostgreSQL, or MySQL to ensure that conversations and agent runs survive system restarts. Developers can deploy it as a complete app using a starter command or integrate it into existing Node 24 projects. The package also provides a ready-to-use chat widget and a streaming service API for building user-facing interfaces.
What you can do with it
- 1Manage sensitive data writesDevelopers can ensure that any tool performing a write operation requires human intervention before proceeding.
- 2Maintain long-running agent sessionsYou can build agents that pick up their exact state after a server reboot or crash.
- 3Integrate diverse AI modelsA single backend can switch between different providers like Ollama or official OpenAI SDKs.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
YADA_LLM_API_KEYYADA_LLM_MODELYADA_LLM_PROVIDERYADA_TEST_MYSQL_URLYADA_TEST_POSTGRES_URL
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 reachableedgar4/yada is public and reachablegithub.com/edgar4/yada ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/edgar4/yada ↗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 GitHubYada
An AI agent harness for TypeScript backends. Bring any model, any MCP server and Agent Skills from Claude, Codex or Cursor; Yada runs the tool loop, asks before it acts, and picks up where it left off after a restart.
- Any model: Anthropic and OpenAI on their official SDKs, Gemini, DeepSeek, Ollama, llama.cpp or any OpenAI-compatible endpoint.
- Any tools: typed tools, MCP servers (stdio or HTTP, OAuth), HTTP APIs, business databases and reusable
SKILL.mdskills. - Safe actions: writes need explicit approval, run at most once and keep durable receipts.
- Durable by default: conversations, runs and approvals survive restarts on SQLite, PostgreSQL or MySQL.
- Ready for users: streaming service API, browser client and an accessible chat widget.
Used by
- Talon: hiring software that gives employers and recruitment agencies one shared workspace for roles, candidates, interviews and offers.
- Tinker Payments: one dashboard for a business's payment providers, to track payments, investigate failed ones and match them to settlements.
- Nairobi Fashion Hub: book models, designers, stylists and photographers in Kenya, and buy tickets to fashion events.
- Tinker Digital: integrations and software that connect legacy systems, payments and operations.
Using Yada in production? Open a pull request to add your project here.
Get started
Two ways in, both on Node 24 or newer.
Start a new agent app
Generate a complete app with storage, skills, typed tools and the chat widget:
npx @edgaralochi/yada init my-agent
cd my-agent
Set your provider credentials in .env, then run npm start. See the starter guide.
Add Yada to an existing backend
npm install @edgaralochi/yada
Import the runtime from @edgaralochi/yada, the browser client from @edgaralochi/yada/client and the widget from @edgaralochi/yada/widget (or the prebuilt @edgaralochi/yada/widget.js script). Narrower entry points are /providers, /storage, /mcp, /skills, /service, /langchain, /otel and /evals; the root exports all of them.
The core and the Anthropic and OpenAI-compatible providers need nothing else. Install only what you use:
| Feature | Install |
|---|---|
| SQLite storage (default) | npm install better-sqlite3 |
| PostgreSQL storage | npm install pg |
| MySQL storage | npm install mysql2 |
| Gemini | npm install @google/genai |
chatModelAdapter (@edgaralochi/yada/langchain) |
npm install @langchain/core |
otelTracer (@edgaralochi/yada/otel) |
npm install @opentelemetry/api |
Use Yada in your backend
import { z } from "zod";
import {
createProvider,
providerConfigFromEnv,
readTool,
run,
} from "@edgaralochi/yada";
const provider = createProvider(providerConfigFromEnv(process.env));
const orderStatus = readTool({
name: "order_status",
description: "Look up an order by ID.",
input: z.strictObject({ id: z.string() }),
authorize: () => Promise.resolve(true),
execute: ({ id }) => Promise.resolve(`Order ${id}: shipped`),
});
const result = await run({
provider,
tools: [orderStatus],
identity: { actorId: "user-1", tenantId: "acme" },
input: "Where is order 1042?",
system: "Help customers with their orders.",
signal: AbortSignal.timeout(30_000),
});
if (result.status === "completed") console.log(result.text);
Set YADA_LLM_PROVIDER, YADA_LLM_API_KEY and optionally YADA_LLM_MODEL. For durable runs, approvals and an HTTP API, see the worker and handler example.
Using a feature without its package fails with an error naming what to install. See provider configuration to choose a model.
Documentation
| Topic | Guide |
|---|---|
| Runtime, limits and termination | Architecture |
| External tool servers | MCP, MCP OAuth |
| Reusable skills | Skills |
| HTTP APIs and databases | Connectors |
| Approved write tools | Actions |
| Conversations and recovery | Storage, Durable runs |
| Service API, streaming and chat UI | Service, Browser SDK and widget |
| Your own name and look for the chat | Widget theming |
| Context, cost, backups and retention | Operations |
| Packaging and Docker | Deployment |
| Agent scenarios in CI and against live models | Evals |
Develop from source
nvm use
npm ci
npm run demo
The demo runs a catalog lookup without an API key. To run it against a live model, copy .env.example to .env, set your provider credentials and run npm run demo:live:
YADA_LLM_PROVIDER=anthropic
YADA_LLM_MODEL=claude-opus-5-5
YADA_LLM_API_KEY=your-anthropic-api-key
That is all Yada needs. .env.example also lists the optional settings (effort, temperature, prompt caching, provider-hosted web search and code execution) with their allowed values; see configuration. Live requests use your provider account and may incur charges; keep .env private. For the full starter, run npm run starter:init, add credentials to .env, then npm run starter.
Before opening a pull request:
npx playwright install chromium
npm run check
npm run test:package
Automated tests require no provider credentials.
Storage tests also run against Postgres and MySQL when these URLs are set. Keep the databases in memory, since tests create and migrate a database each and that is many times slower on disk:
docker run -d --rm --name yada-test-pg --tmpfs /var/lib/postgresql/data -e POSTGRES_PASSWORD=yada-test -e POSTGRES_DB=yada_test -p 55432:5432 postgres:17
docker run -d --rm --name yada-test-my --tmpfs /var/lib/mysql -e MYSQL_ROOT_PASSWORD=yada-test -e MYSQL_DATABASE=yada_test -p 53306:3306 mysql:8.4
export YADA_TEST_POSTGRES_URL=postgres://postgres:yada-test@127.0.0.1:55432/yada_test
export YADA_TEST_MYSQL_URL=mysql://root:yada-test@127.0.0.1:53306/yada_test
Upgrading from 0.4
- The widget has a new default look: monochrome, with Yada's changing face in the header and on the empty screen, a single-line input and an icon send button. The title now defaults to "Yada". Set
avatar: false,composer,labels.titleand the--yada-*variables to change these, orunstyledto drop the styles. - The approve button is now green and decline red. Set
--yada-approveand--yada-declineto keep your own. - Runs have a new failure code,
corrupt_record. Handle it wherever you switch on failure codes.Tracehas a newrecord_quarantinedevent. BrowserClientrequests now time out after 15 seconds. SettimeoutMsto change it, or0for the old behavior.- Run settings changed through getters now apply from the next run. Before, changing
limitsor the provider's name mid-run failed that run when it resumed.
Upgrading from 0.3
- MCP schemas now enforce standard JSON Schema formats such as
uuidanddate-timeon inputs, outputs and elicitation answers. A server output that fails its format after a write ran is treated as a possibly applied action and goes to reconciliation. - Actions have a new
undeliveredstatus for writes that were never sent. Handle it wherever you switch on action status. - Runs that exhaust their retries now add their cost to quotas.
Upgrading from 0.2
better-sqlite3,pg,mysql2,@google/genai(Gemini) and@langchain/core(chatModelAdapterfrom@edgaralochi/yada/langchain) are optional peer dependencies; install the ones you use.@langchain/google-genai,@langchain/anthropicand@langchain/openaiare no longer used; Anthropic and OpenAI-compatible providers run on the official SDKs.ReadTool.executereturnsContent(a string or an array of text and image parts) instead ofstring.- Hosted
openaialways uses the Responses API; theapioption andYADA_LLM_OPENAI_APIare removed. - Provider-hosted web search is on by default for
anthropic,openaiandgeminiand is billed by the provider; setYADA_LLM_SERVER_TOOLS=noneto turn it off. - Every provider accepts every model setting and ignores ones it has no equivalent for (Anthropic ignores
temperature; useeffort). chatModelAdaptermoved to@edgaralochi/yada/langchain, andotelTraceris only exported from@edgaralochi/yada/otel.- Storage writes use a new encryption envelope with key ids (
v1records stay readable) and an indexedactivecolumn; stop older Yada versions before upgrading, since they cannot read new records. SetYADA_STORAGE_PREVIOUS_KEYSto rotate keys without downtime. - The service returns 400, 404, 410 and 415 for client errors instead of 503, and JSON endpoints require
Content-Type: application/json. maxFailurescounts consecutive rounds in which every tool call failed, and tools time out afterlimits.toolTimeoutMs(default 120,000).maxContextCharsdefaults to 256,000 and servicehistoryCharsto 128,000.maxRoundsdefaults to 32 andmaxToolCallsto 64, also forrunDurableand worker profiles. SetmaxCostMicrosto bound spend. Durable runs suspended before the upgrade fail withRun configuration mismatchon resume unless their profile pins the oldmaxRounds: 8andmaxToolCalls: 16.
License
Yada MCP questions
What models can Yada use?
Yada supports Anthropic, OpenAI, Gemini, DeepSeek, Ollama, llama.cpp, or any OpenAI-compatible endpoint.
How does Yada handle tool execution and safety?
It runs a tool loop and requires explicit approval for write actions to ensure safety.
Can Yada persist conversation data?
Yes, conversations, runs, and approvals are durable and can be stored using SQLite, PostgreSQL, or MySQL.
Does Yada support MCP servers?
Yes, it can integrate with any MCP server using either stdio or HTTP protocols, including OAuth.