instant-mcp

English | 한국어

A local mock MCP server for people building against the Model Context Protocol. Write a tool in the browser, save it, and it is immediately available on an MCP endpoint. There is no restart or deploy step.

Point your MCP client at http://127.0.0.1:4100/mcp/default and start working.

import { defineTool } from "instant-mcp";

export default defineTool({
  description: "Look up a user by name",
  inputSchema: {
    type: "object",
    properties: { name: { type: "string" } },
    required: ["name"],
  },
  handler(args: { name: string }, ctx) {
    return ctx.db.query("SELECT * FROM users WHERE username = ?", [args.name]);
  },
});

Features

• Hot reload. Save a tool and the endpoint serves the new version on the next request. Editing in the web UI and editing the file directly both work.
• Multiple endpoints. Group tools and serve each group at /mcp/<slug>, so different clients can see different tool sets.
• A mock database. Create SQLite tables in the UI and read or write them from tool code through ctx.db.
• A call log. Every MCP call is recorded with its arguments, result, errors and duration, so you can see the arguments a client actually sent.
• A control endpoint. Optionally expose instant-mcp itself over MCP so a coding agent can author tools, wire endpoints and read the call log.

Everything runs locally with no authentication. The server binds to 127.0.0.1 only.

Quick start

Requires Node 20 or newer.

git clone https://github.com/jhleee/instant-mcp.git
cd instant-mcp
npm install
npm run build     # build the web UI once
npm start         # http://127.0.0.1:4100

The first run copies two example tools into data/tools/.

Register it with an MCP client:

{
  "mcpServers": {
    "instant-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:4100/mcp/default"
    }
  }
}

For UI development, npm run dev runs the server and Vite together. The UI is on http://127.0.0.1:5173 and proxies API and MCP traffic to port 4100.

Writing tools

A tool is a directory under data/tools/ with an index.ts that default-exports one module. The authoring API comes from the instant-mcp module, so there is no need for relative paths into the server.

defineTool returns its argument unchanged. It exists for typing: use it and ctx is inferred without an annotation. A plain export default { ... } also works.

• A handler that returns a string sends it as-is. Any other value is JSON-stringified. Return { content: [...] } to build the MCP payload yourself.
• inputSchema is used for validation, not just documentation. A call missing a required field is rejected before the handler runs.
• Saving recompiles and reloads the tool, whether you save from the web UI or edit the file directly.

What ctx can do

The full API is in sdk/index.d.ts. The server implementation is type-checked against that file and the web editor loads the same file, so the documentation stays in step with the behaviour.

There are three ways to read it:

1. Editor autocomplete. Type ctx. inside a handler to get the methods with their docs and examples.
2. The Context API button in the sidebar footer, which renders the declaration file.
3. npm run typecheck, which covers data/tools/** along with the server.

ctx.db is the only route to the mock tables:

Method	Purpose
tables()	Names of all mock tables
all(table, limit?)	Every row, up to limit (default 500)
query(sql, params?)	Read-only SELECT with ? placeholders
insert(table, values)	Insert a row, returns the new id
update(table, id, values)	Update only the columns given
delete(table, id)	Delete a row

Groups and endpoints

Tools belong to groups, and each group is served at its own endpoint. New tools join the default group automatically. Endpoints use stateless Streamable HTTP and are rebuilt per request, so hot reloads and enable/disable changes take effect right away.

Mock tables

Create tables and edit rows under Mock Tables in the sidebar. Every table gets an auto-increment id. Names beginning with _ and the sqlite_ prefix are rejected to protect the metadata tables, and identifiers are validated before they reach SQL.

Call log

Every tool call arriving over MCP is recorded: time, group, tool, arguments, result, error flag and duration. Read it under Call Log in the sidebar, or with get_call_log on the control endpoint.

This matters when you are testing someone else's client, because it shows the arguments that were sent rather than the ones that were intended. Calls rejected by argument validation are logged too. The log keeps the most recent 2000 entries and truncates large payloads.

Control endpoint (/mcp/_control)

An optional endpoint that exposes instant-mcp itself over MCP, so a coding agent can build and debug a mock server.

npm run start:control        # or INSTANT_MCP_CONTROL=1 npm start

{
  "mcpServers": {
    "instant-mcp-control": {
      "type": "http",
      "url": "http://127.0.0.1:4100/mcp/_control"
    }
  }
}

Tools

Tool	Purpose
describe_workspace	One call returns tools, groups, endpoint URLs and tables
read_tool	A tool's source
write_tool	Create or update. Returns loadError, so the caller knows whether the code compiled
delete_tool	Remove a tool
run_tool	Execute directly, bypassing MCP, to check a tool before handing over an endpoint
write_group / delete_group	Manage endpoints. write_group returns the URL
write_table / drop_table	Mock schema
seed_table	Bulk insert (append or replace)
query_sql	Read-only SELECT
get_call_log	What clients actually sent

There is no per-row CRUD. Inserting twenty rows should be one seed_table call rather than twenty round trips.

Resources

• instant-mcp://sdk is the tool authoring API. Read it before writing tool code and there is nothing to guess about ctx.
• instant-mcp://tools/{name} is a tool's source.
• instant-mcp://groups/{slug} is the tools/list payload that endpoint serves, which is what a client will see rather than internal state.

Isolation

The control surface is a fixed endpoint outside the normal group namespace, so an agent cannot disable the tools it is calling through:

• Slugs starting with _ are reserved, so no group can shadow _control.
• Control tools are built into the server rather than stored under data/tools/, so write_tool and delete_tool cannot reach them and they cannot be disabled.
• _control never appears in the group list, so it cannot be edited or deleted.

npm run smoke:guards checks all four.

Security

This endpoint is effectively an arbitrary code execution API. write_tool writes files under data/tools/ and that code runs unsandboxed inside the server process, which is why it is off until you turn it on. The web UI has the same power, but exposing it over MCP means any client that knows the URL has it too.

Enable it for local mock work only.

Project layout

sdk/index.d.ts     the tool authoring API
sdk/index.js       defineTool runtime
server/
  index.ts         entry point: REST API, MCP and the static UI on one port
  db.ts            SQLite schema and mock table CRUD
  toolLoader.ts    esbuild transpile, dynamic import, chokidar hot reload
  workspace.ts     tool/group/table operations shared by REST and control MCP
  mcp.ts           per-group MCP server (tools/list, tools/call)
  control.ts       control MCP: 12 tools and 3 resources
  callLog.ts       MCP call recording
  toolContext.ts   the ctx injected into tool handlers
  routes/          apiRoute.ts (REST), mcpRoute.ts (/mcp/:slug)
web/               Vite, React, shadcn/ui, Monaco
examples/tools/    example tools, copied into data/tools on first run
data/              your workspace: tool code, SQLite db, build output (untracked)

Scripts

Command	Purpose
npm run dev	Server and Vite together
npm start	Server only, serving the built UI
npm run start:control	Also enable the control endpoint
npm run build	Build the web UI
npm run typecheck	Type-check everything, including your tools
npm run smoke	Connect an MCP client to /mcp/default
npm run smoke:control	Author a tool, wire an endpoint, call it, read the log
npm run smoke:guards	Control endpoint isolation checks

Limitations

Tool code runs unsandboxed in the server process, so only load code you trust. Sandboxing with vm is planned but not implemented.

The transport is stateless, so there is no notifications/tools/list_changed push and clients have to re-list to see new tools. Each request rebuilds the server, so re-listing always returns current state.

Contributing

Issues and pull requests are welcome. Please run npm run typecheck and npm run build before opening a PR.

License

MIT