instamcp

An instant MCP (Model Context Protocol) server for Node.js. Define tools in instamcp.js and they're immediately available via HTTP/HTTPS endpoints - no configuration needed. Uses Node.js built-in web server (no dependencies).

Quick Start

Using npx (recommended)

Run directly with npx, specifying the path to your tools file:

npx instamcp ./my-tools.js

Or use the default instamcp.js in the current directory:

npx instamcp

HTTPS Support

To run with HTTPS, first generate SSL certificates:

npm run generate-certs
# or
node generate_certs.js

Then start the server with HTTPS:

npx instamcp --https

Or specify custom certificate paths:

npx instamcp --https --key ./custom-key.pem --cert ./custom-cert.pem

Local Installation

npm install
npm start

Or install globally:

npm install -g instamcp
instamcp ./my-tools.js

API Endpoints

Replace http:// with https:// if using HTTPS.

Initialize

Initialize the MCP server and get available tools:

curl -X POST http://localhost:3000/initialize \
  -H "Content-Type: application/json"

Update

Reload tools from instamcp.js without restarting:

curl -X POST http://localhost:3000/update \
  -H "Content-Type: application/json"

List tools

curl http://localhost:3000/tools

Call a tool

curl -X POST http://localhost:3000/tools/greet \
  -H "Content-Type: application/json" \
  -d '{"name": "World"}'

For HTTPS with self-signed certificates, use -k flag:

curl -k -X POST https://localhost:3000/tools/greet \
  -H "Content-Type: application/json" \
  -d '{"name": "World"}'

Defining Tools

Edit instamcp.js to add tools. Each tool should have:

• name: Tool identifier
• description: What the tool does
• inputSchema: JSON schema for input validation
• handler: Async function that processes the input

Example Tool Definition

export default {
  greet: {
    name: "greet",
    description: "Greets a person by name",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "The name to greet" }
      },
      required: ["name"]
    },
    handler: async ({ name }) => {
      return `Hello, ${name}!`;
    }
  },
  add: {
    name: "add",
    description: "Adds two numbers",
    inputSchema: {
      type: "object",
      properties: {
        a: { type: "number", description: "First number" },
        b: { type: "number", description: "Second number" },
        c: { type: "number", description: "Optional third number" }
      },
      required: ["a", "b"]  // 'c' is optional
    },
    handler: async ({ a, b, c = 0 }) => {
      return a + b + c;
    }
  }
};

Required vs Optional Properties

• Required properties: Include in the required array
• Optional properties: Omit from the required array, use default values in the handler (e.g., c = 0)

Reloading Tools

After editing instamcp.js, call /update to reload tools without restarting the server.