Ishtaran MCP

The official knowledge, discovery, planning, and validation layer for AI agents building on Ishtaran. It never executes financial operations -- no deposits, settlements, payouts, withdrawals, or refunds. Use one of the Ishtaran SDKs to actually integrate; use this server first so your agent doesn't hallucinate an endpoint, SDK method, error code, or webhook event that doesn't exist.

LLM thinks  ->  MCP teaches/plans/validates  ->  SDK executes the integration  ->  API executes the business

What it is not

Not an Admin Console, not a code generator, not a deployer, not a way to touch Production, and not a way to move money. If a tool result ever looks like it did something financial, that's a bug -- please open an issue.

Install

No API key or environment variable is required -- every tool and resource works fully offline, right after install, using the Knowledge Bundle shipped inside the package.

Claude Code

Add to your project's .mcp.json (or run claude mcp add):

{
  "mcpServers": {
    "ishtaran": {
      "command": "npx",
      "args": ["-y", "@ishtaran/mcp"]
    }
  }
}

Claude Code will prompt you to approve the new server the next time you open the project.

Cursor

Settings -> MCP -> Add new MCP server:

{
  "mcpServers": {
    "ishtaran": {
      "command": "npx",
      "args": ["-y", "@ishtaran/mcp"]
    }
  }
}

VS Code (or any other stdio-based MCP client)

Point the client at the command npx -y @ishtaran/mcp with no arguments and no environment variables. Any client that speaks MCP over stdio works the same way.

Run it directly

npx -y @ishtaran/mcp

This starts the stdio server. It's meant to be launched by an MCP client, not used interactively.

First questions to try

• "How do I integrate Ishtaran?"
• "Build a marketplace using Ishtaran."
• "How do I verify an Ishtaran webhook?"
• "Explain NETWORK_EXECUTION_FEE_INSUFFICIENT_BALANCE."
• "What's the difference between Settlement and Payout?"
• "Can a Withdrawal pull from multiple accounts?" -- ask directly, or hand a claim like that to validate_integration_plan; it will tell you no and why.

The marketplace recipe

get_recipe with recipeId: "marketplace" points at marketplace-mercatto, a real, runnable reference implementation (buyer/seller Accounts, PaymentIntent funding, partial/full Settlement with PlatformFee and per-participant revenue split, MANUAL Payout, refunds, and the full webhook lifecycle) maintained in the main Ishtaran monorepo. wallet-payment-app and service-milestone are real, supported patterns (recipeStatus: SUPPORTED_CONCEPT) but have no reference project yet (referenceProjectStatus: PLANNED) -- the tools say this explicitly rather than pointing you at code that doesn't exist.

Resources vs Tools vs Prompts

• Resources (ishtaran://...) are for browsing/reading -- an index, a capability, an operation, an error, a webhook event, a recipe, a reference project, the glossary.
• Tools are for asking a specific question or getting a computed answer. Eleven tools cover the full V1 surface -- search (search_knowledge), capability lookup (get_capability), operation lookup (get_operation), SDK method lookup (choose_sdk), error explanation (explain_error), webhook contract (get_webhook_contract), integration recipes (get_recipe), integration planning (plan_integration), plan validation (validate_integration_plan), and knowledge freshness (get_knowledge_status, update_knowledge).
• Prompts are pre-built starting points for common tasks (integrate_ishtaran, build_marketplace, build_wallet, build_service_marketplace, debug_ishtaran, implement_webhook_receiver, review_ishtaran_integration).

Staying current without reinstalling

The Engine package (@ishtaran/mcp) and the Knowledge Bundle it ships with are versioned independently. The package version (e.g. 0.1.0) only changes when the server's code -- resources, tools, prompts, protocol behavior -- changes. The Knowledge Bundle (its own knowledgeVersion, e.g. 2026.09.09.abc123) changes whenever public docs, the OpenAPI contract, SDK methods, recipes, or reference projects change -- which is far more often, and does not require a new package release.

On startup, the server reads its embedded Knowledge Bundle immediately (never blocks on network), then checks a small public manifest in the background, best-effort. get_knowledge_status shows whether a newer bundle is available; update_knowledge (with consent: true) downloads and applies it. New docs, routes, capabilities, recipes, and reference projects can reach you this way -- you normally do not need to run npx @ishtaran/mcp again or reinstall anything.

Updates are DATA only (a JSON bundle, HTTPS-fetched, SHA-256-verified, schema-validated, atomically swapped) -- never remotely executed code, and update_knowledge never runs without explicit consent. If the bundle ever requires a newer Engine than you have installed, the server tells you so explicitly rather than silently failing or fetching arbitrary code.

Development (working in the Ishtaran monorepo)

cd mcp
npm install
npm run build:knowledge   # generates mcp/knowledge/<version>/*.json from the current repo state
npm run typecheck
npm test                  # full suite: unit, contract, golden, anti-pattern, marketplace, update
npm run build             # bundles mcp/dist/index.js
npm run ci                # everything above, in the same order CI runs it

mcp/build/ is the Knowledge Build System (reads public sources only -- OpenAPI, SDK source, AI docs, hand-authored errors/webhooks/glossary/gaps/recipes/projects -- and writes mcp/knowledge/<version>/*.json). It only runs inside the Ishtaran monorepo, since it cross-references the live OpenAPI contract and all 4 official SDKs' source trees, none of which exist in this standalone repo -- that's why this repo's CI does not run build:knowledge and instead tests against the already-committed bundle. mcp/src/ is the Engine (resources/tools/prompts/search/cache/update logic) and rarely needs to change when only the knowledge bundle changes.

To point a local MCP client at your own build instead of the published package, use node /absolute/path/to/mcp/dist/index.js as the command with no arguments.

Troubleshooting

• "No shipped knowledge bundle found" -- run npm run build:knowledge before npm run build (only relevant when building from source; the published package always ships a bundle).
• A tool call fails with isError: true -- this is a normal, recoverable "unknown id" or "not supported" response (e.g. an admin operationId, a nonexistent webhook event). Read the message; it's the answer, not a bug.
• Everything looks stale -- call get_knowledge_status; if updateAvailable is true, call update_knowledge with consent: true.

License

Apache-2.0 -- see LICENSE.