MCP-GRID

bprabin811/MCP-GRID

3.1

If you are the rightful owner of MCP-GRID and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Next.js is a Next.js application that provides utility tools through the Model Context Protocol (MCP).

MCP GRID — Next.js MCP Tool Builder

Create, manage, and run tools locally or from external MCP servers with a clean UI, schema-driven forms, and live results.

Overview

This app is a Next.js 15 tool playground that speaks the Model Context Protocol (MCP). It lets you:

  • Run built-in MCP tools exposed by the bundled server endpoints
  • Create your own tools as either API calls (REST) or custom JavaScript logic
  • Discover and call tools from external MCP servers (SSE or Streamable HTTP), with a server-side proxy to avoid CORS
  • Toggle storage between localStorage and a Postgres database per user

It’s great for prototyping tool ideas, testing MCP servers, and building small utilities you can share.

Features

  • Schema-driven forms: auto-generate inputs from JSON-schema-like tool definitions
  • API tools: configure URL/method/headers and query/body params; paste cURL to prefill
  • Custom-logic tools: write JS to return MCP-formatted results or plain text
  • Array/object parameters: enter JSON directly for complex inputs
  • External MCP servers: connect via SSE or Streamable HTTP with auth headers/API keys
  • Storage modes: localStorage (default) or per-user Postgres via NextAuth
  • Live results: responses rendered in a readable MCP result format

Requirements

  • Node.js 18.18+ (20+ recommended)
  • npm 9+
  • Optional Postgres database (for persistent, per-user storage)
  • GitHub OAuth app (for NextAuth when using Postgres mode)

Environment variables

Copy env.example to .env.local and fill in values:

NEXT_BASE_URL=http://localhost:3004         # base URL used by server-side MCP client
NEXTAUTH_URL=http://localhost:3004          # NextAuth callback URL
DATABASE_URL=postgres://user:pass@host:5432/dbname
GITHUB_CLIENT_ID=xxxxx
GITHUB_CLIENT_SECRET=xxxxx
NEXTAUTH_SECRET=your-long-random-string

Notes:

  • NEXT_BASE_URL is used server-side to connect the MCP client to this app’s own MCP endpoint.
  • DATABASE_URL is only required when you enable “Use Database” in Settings.
  • For local dev, put all values in .env.local.

Getting started

  1. Install dependencies
npm install
  1. (Optional) Configure database + auth
  • Create a Postgres database and set DATABASE_URL
  • Create a GitHub OAuth app (Homepage URL and Callback set to NEXTAUTH_URL)
  • Set GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, NEXTAUTH_SECRET
  1. Initialize database (only if using Postgres mode)
npm run init-db
  1. Start the dev server
npm run dev

App will be available at http://localhost:3004

Usage walkthrough

Pages/routes:

  • / — Playground: pick a tool on the left, fill the form, run, and see results
  • /tool-management — Create/edit custom tools (API or JS)
  • /external-servers — Configure external MCP servers (SSE or Streamable HTTP, with headers/API key)
  • /setting — Per-user setting to enable “Use Database” (requires sign in)
  • /auth/signin — NextAuth sign-in (GitHub)

Custom API Tools

  • Paste cURL: auto-detect method, URL, headers, and infer parameters (JSON body and form-urlencoded supported)
  • Query/body separation: define querySchema and inputSchema so params go to the right place
  • Arrays/objects: JSON values go in as structured data; query params are JSON-stringified, body is JSON

Custom Logic Tools

  • Write plain JS; you get safe globals (console, JSON, Math, etc.)
  • Return either a string or an MCP-style object: { content: [{ type: 'text', text: '...' }] }
  • Errors are captured and returned as readable text

External MCP Servers

  • Add servers with SSE or Streamable HTTP transport
  • Optional auth: Bearer or API-Key, plus custom headers
  • Server-side proxy endpoints avoid browser CORS and can keep SSE sessions alive

Storage modes

  • localStorage (default, no auth required)
  • Postgres (enable in /setting). Requires GitHub sign-in. Tools and external servers are stored per-user.

MCP server endpoints in this app

Backed by @vercel/mcp-adapter:

  • Streamable HTTP: POST/GET /api/mcp (adapter basePath "/api", streamableHttpEndpoint "/mcp")
  • SSE: GET /api/sse

The server also registers helper tools (json_formatter, base64_converter, hash_generator, etc.) and dynamically registers your custom tools from the database with a small cache for fast refreshes. A special tool refresh_custom_tools forces a cache refresh.

Programmatic client usage (inside this app) uses setupClient in utils/clientUtils.ts, connecting to NEXT_BASE_URL/api/mcp.

Project structure

app/
  api/[transport]/route.ts      # MCP adapter handler (streamable-http + SSE)
  api/tools/route.ts            # CRUD for custom tools (DB mode)
  api/external-servers/route.ts # CRUD for external MCP servers (DB mode)
  api/external-mcp/route.ts     # Proxy for external MCP over Streamable HTTP
  api/sse-connect/route.ts      # Proxy + sessionizer for external MCP over SSE
  api/settings/route.ts         # Per-user setting: useDb
  ... UI pages (/, /tool-management, /external-servers, /setting, auth)

components/                     # UI (Tool list/panel, forms, editors)
hooks/                          # useTools, useToolExecution, useExternalServers
lib/                            # Postgres adapter + schema helpers
utils/                          # clientUtils, toolStorage, toolExecutors, parseCurl
types/                          # Shared TypeScript types
scripts/init-db.ts              # Initialize DB schema (Postgres)

Scripts

  • dev: next dev --turbopack --port 3004
  • build: next build --turbopack
  • start: next start
  • lint: eslint
  • init-db: tsx scripts/init-db.ts

Deployment notes

  • This app uses Next.js Route Handlers and Node runtime for long-lived connections (SSE). Ensure your platform supports persistent requests for /api/sse when using SSE external servers.
  • If your platform is serverless and limits SSE, prefer Streamable HTTP transports for external servers (/api/external-mcp proxy).
  • Set all env vars and a strong NEXTAUTH_SECRET in production.

Troubleshooting

  • 401 on saving tools/servers: You must sign in (GitHub) and enable “Use Database” in /setting.
  • Database mode does nothing: Ensure DATABASE_URL is set and run npm run init-db; then toggle “Use Database”.
  • External server calls fail: Check server URL, transport type, and auth; for SSE, verify your host allows long-lived connections.
  • Tool doesn’t refresh: Run the refresh_custom_tools tool or wait a few seconds (cache TTL ~5s).
  • Server-side MCP connection fails: Set NEXT_BASE_URL to the public URL in production.

Security

  • User-added JS runs in a limited, sandbox-like function with safe globals only; no direct access to Node APIs.
  • Secrets belong in environment variables; do not hardcode API keys.
  • When connecting to external MCP servers, headers are proxied server-side to avoid exposing secrets to the browser.

License

MIT — see LICENSE

Acknowledgments

  • Next.js, TypeScript, Tailwind CSS
  • @vercel/mcp-adapter and @modelcontextprotocol/sdk
  • Radix UI + Lucide Icons

Happy building! 🚀