mcpconsole

README

mcpconsole

An embeddable, schema-driven web console for MCP servers, in one line of Go:

mux := http.NewServeMux()
mux.Handle("/mcp", mcpHandler)                 // any MCP streamable-HTTP handler
mux.Handle("/ui/", mcpconsole.Handler("/mcp")) // this library

The UI is generated entirely from the MCP protocol definition: it initializes a session, calls tools/list, and renders an input form for each tool from its JSON input schema.

The library has no Go dependencies apart from the standard library. All frontend assets are embedded.

The frontend uses (vendored) hyperapp.js.

NOTE: I'm using the library and testing it against github.com/modelcontextprotocol/go-sdk. It would be interesting to see how well it works with other libraries.

Usage

import "github.com/bilus/mcpconsole"

func main() {
	server := mcp.NewServer(&mcp.Implementation{Name: "adder", Version: "0.1.0"}, nil)
	mcp.AddTool(server, /* … */)

	mux := http.NewServeMux()
	mux.Handle("/mcp", mcp.NewStreamableHTTPHandler(
		func(*http.Request) *mcp.Server { return server }, nil))
	mux.Handle("/ui/", mcpconsole.Handler("/mcp", mcpconsole.WithTitle("Adder - MCP Console")))
	log.Fatal(http.ListenAndServe("localhost:8080", mux))
}

For more examples see: examples/README.md.

Options

Option	Effect
WithTitle(string)	Page title. Default "MCP Console".

Schema coverage

The form renderer is deliberately conservative: it builds native controls for what it can represent faithfully and falls back to a raw-JSON editor for everything else.

Schema construct
string
number / integer
boolean
enum / const (scalars)
array of primitives/enums
nested object
required, description, default
oneOf / anyOf / allOf / not / $ref / if–then / union types / patternProperties / map-style objects / arrays of objects / depth > 4 *

• JSON fallback

Testing

Unit tests:

go test ./...

Browser tests (require a local Chrome/Chromium):

cd examples
go test -tags e2e ./...

License

MIT, see LICENSE.

Documentation

Overview

Package mcpconsole serves an embeddable, schema-driven web console for MCP servers.

Index

• func Handler(mcpEndpoint string, opts ...Option) http.Handler
• type Option
  • func WithTitle(title string) Option

Functions

func Handler

func Handler(mcpEndpoint string, opts ...Option) http.Handler

Handler returns an http.Handler serving the console UI generated based on the provided MCP endpoint (e.g. "/mcp").

Types

type Option

type Option func(*config)

Option customizes the console handler.

func WithTitle

func WithTitle(title string) Option

WithTitle sets the console title shown in the page <title> and the left rail. The default is "MCP Console".