OpenBook MCP Server

A Spring Boot and Spring AI MCP server using Streamable HTTP. The /mcp endpoint is protected with GitHub OAuth access tokens supplied as Bearer credentials. Authenticated GitHub tools use the caller's token; Open Library tools access its public read APIs without forwarding credentials.

Requirements

• Java 25
• Maven 3.9+

Run

mvn spring-boot:run

The MCP endpoint is http://localhost:8091/mcp. Health information is available at http://localhost:8091/actuator/health.

Authentication

Register a GitHub OAuth App and configure the MCP client to obtain and send its GitHub access token as Authorization: Bearer <token>. The server validates each presented token by calling GitHub's authenticated-user API (GET https://api.github.com/user). It does not mint, exchange, or persist tokens. The authenticated identity and token are request-scoped; GitHub API tools use the token of the current caller.

GitHub OAuth Apps do not provide the OAuth authorization-server metadata, dynamic client registration, or gateway-audience tokens required for automatic MCP browser OAuth discovery. Therefore clients must be configured with the GitHub OAuth App outside the gateway. This server deliberately does not publish misleading /.well-known metadata or pretend that a GitHub access token is an audience-restricted gateway token. Use HTTPS when exposing the endpoint beyond localhost.

Use only the GitHub permissions required by the client. Do not put tokens in tool arguments, source control, or logs.

Tools

Diagnostic tools include ping, who_am_i, and verify_connectivity.

GitHub tools are read-only and include repository search/list/get, branches, file contents, commits, pull requests and review data, issues and comments, Actions workflows/runs/jobs, and a constrained raw GET fallback. Private resource access is controlled by the calling user's GitHub permissions. Action logs are size-limited and undergo best-effort secret redaction; undetected secrets may still be present.

Open Library tools are public and read-only. They cover book/work/author search, structured search, edition and ISBN lookup, author works, subjects, cover metadata, unified search, and a constrained raw GET fallback. Work, edition, and author identifiers are validated separately. Pagination is bounded, responses are size-limited, and public responses are cached in a bounded in-memory Caffeine cache. No GitHub or gateway credential is sent to Open Library.

Set OPENLIBRARY_CONTACT to include a contact address in the descriptive Open Library User-Agent. Open Library access can be disabled with GATEWAY_OPENLIBRARY_ENABLED=false; its tools and catalog resources are then not registered. The cache defaults to 500 entries with a 30-minute TTL and can be adjusted using gateway.openlibrary.cache.maximum-size and gateway.openlibrary.cache.ttl.

Open Library API references:

• Search
• Books and editions
• Authors
• Subjects (experimental)
• Covers

Check with MCP Inspector

Start the server, then point MCP Inspector at http://localhost:8091/mcp. Initialize the connection, list tools and resources, and call ping.

Build and test

mvn clean verify