Dev.to AI 🤖 Ai 👁 0 📖 8 min read

Making a Remote MCP Server Discoverable Without Opening Tool Access

We run a remote MCP server at https://app.neuron.expert/api/v1/mcp. It uses Streamable HTTP, is stateless, accepts POST requests, speaks JSON-RPC 2.0, and does not accept batch requests. GET returns 405. The server is a

We run a remote MCP server at https://app.neuron.expert/api/v1/mcp. It uses Streamable HTTP, is stateless, accepts POST requests, speaks JSON-RPC 2.0, and does not accept batch requests. GET returns 405.

The server is a read-only window into one business's Neuron data, opened by that business's owner. Neuron combines a phone receptionist, CRM, and website for home-service businesses. Our MCP server has 10 read-only tools for calls, leads, jobs, usage, business details, services, site pages, inbox messages, bookings, and contacts.

The idea behind this change is simple: make discovery open, but keep every tool call behind OAuth 2.1.

The problem

Directories and clients need to inspect an MCP server before they can know what it offers. In practice, that means probing initialize and tools/list.

Before this change, our server returned 401 Unauthorized to both methods when no token was present. On November 16, 2026, mcptry.com, a catalogue that reads the official MCP Registry and probes remote servers, rated the server 62/100 and ranked it #1409 of 4,994 in its "AI & Agents" category. Its main named gap was that initialize and tools/list returned HTTP 401 without a token, a gap worth up to +30 points.

Dropping authorization entirely was not an option. The server exposes business data, and tool execution must remain tied to the business owner, the granted scopes, and the token audience.

We also did not want a special unauthenticated mode that accidentally leaked data. Discovery should reveal the server's shape, not any business's data.

Splitting public and authenticated methods

We split the MCP methods into a small public discovery surface and the normal authenticated path.

The public allow-list is exactly initialize, ping, and tools/list. tools/call is never public. Unauthenticated notifications are accepted and answered with HTTP 202.

/** Methods an unauthenticated client may call. `tools/call` is never one of them. */
export const MCP_PUBLIC_METHODS: readonly string[] = ["initialize", "ping", "tools/list"];

/**
 * The answer to a request with no credential at all, or `undefined` when the request
 * needs one (the caller then answers 401 + WWW-Authenticate). Pure: no database, no tenant.
 */
export function handlePublicMcp(msg: any): any | null | undefined {
  const checked = validateMcpMessage(msg);
  if (!checked.ok) return mcpError(checked.id, checked.code, checked.message);
  if (msg.method.startsWith("notifications/")) return null;
  if (!MCP_PUBLIC_METHODS.includes(msg.method)) return undefined;
  if (msg.id === undefined) return mcpError(null, -32600, "request id required");
  const reply = (result: any) => ({ jsonrpc: "2.0", id: msg.id, result });
  if (msg.method === "initialize") return reply(mcpInitializeResult(msg?.params?.protocolVersion));
  if (msg.method === "ping") return reply({});
  return reply({ tools: mcpToolCatalog(null) }); // null = the full static catalog
}

The route keeps the distinction intentionally narrow: no credential at all can use the public handler. A request that sends an Authorization header is judged by the existing authenticated path exactly as before.

app.post("/api/v1/mcp", async (req, res) => {
  // ... transport checks (content type, Accept, protocol version, Origin) ...

  // No credential at all -> the static catalog for initialize / ping / tools/list.
  // A request that sends ANY Authorization header is judged by `guarded` exactly as before.
  if (!req.headers.authorization) {
    const byIp = publicMcpRate.take(`ip:${req.ip || "?"}`, Date.now()); // 60 a minute
    if (!byIp.ok) {
      res.setHeader("Retry-After", String(byIp.resetSec));
      return void res.status(429).json({ error: "rate_limited" });
    }
    const open = handlePublicMcp(req.body);
    if (open !== undefined) {
      if (open === null) return void res.status(202).end(); // notification
      return void res.json(open);
    }
  }
  const g = await guarded(req, res); // 401 + WWW-Authenticate when the token is missing or bad
  if (!g) return;
  res.json(await handleMcp(g.d, g.claims, req.body, Date.now()));
});

This means an invalid token still gets a 401, even for initialize and tools/list. We wanted to avoid confusing half-authenticated states where a malformed or expired credential silently falls back to public behavior.

The public catalog is static. It comes from a shared constant and does not access a database, claims, or business data. It is identical for everyone and matches the full catalog visible to a token with all scopes. Public discovery is rate-limited to 60 requests per minute per IP address; requests beyond that receive 429 with Retry-After.

Each catalog entry includes a title, description, input schema, read-only annotations, and an OAuth security scheme for its scope. The annotations do not authorize anything. Scope and business checks stay on the server.

This was also safe because the catalog only describes input shapes. It never contains data. Calls, leads, and jobs look backward using optional ISO date or datetime from and to values; to defaults to now and from defaults to seven days before to. Their window is at most 90 days, with at most 500 rows per answer.

Bookings look forward instead: optional from and to are YYYY-MM-DD calendar dates, from defaults to today in UTC, and to defaults to seven days after from. That window is also at most 90 days, with at most 500 rows. Usage reports this month's plan usage. Business, services, site pages, and inbox take no arguments; services, site pages, and inbox return at most 500 rows. Contacts require a printable 3-80 character query and return at most 25 results, so the CRM cannot be enumerated through that tool. No tool accepts a business selector.

The server supports MCP protocol versions 2025-03-26 and 2025-06-18. During initialization, it echoes a supported requested version, or uses 2025-03-26, and sends the same value in the MCP-Protocol-Version header.

The OAuth discovery flow

A public tools/list now returns 200 without a token. A tool call without one still receives the existing challenge:

# Discovery: no token, 200
curl -s https://app.neuron.expert/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# A tool call without a token: 401 and a pointer to the OAuth metadata
curl -si https://app.neuron.expert/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"neuron_usage","arguments":{}}}'
# HTTP/1.1 401
# WWW-Authenticate: Bearer resource_metadata="https://app.neuron.expert/.well-known/oauth-protected-resource/api/v1/mcp", error="invalid_token", ...

curl -s https://app.neuron.expert/.well-known/oauth-protected-resource/api/v1/mcp
curl -s https://app.neuron.expert/.well-known/oauth-authorization-server

The WWW-Authenticate header points clients at protected-resource metadata, following RFC 9728. That metadata identifies the resource, supported bearer method, supported scopes, and the authorization server. The authorization-server metadata then identifies dynamic client registration, authorization, and token endpoints.

Our server implements OAuth 2.1. Clients can dynamically register at /api/v1/oauth/register, authorize at /api/v1/oauth/authorize, and exchange tokens at /api/v1/oauth/token. Public clients use token_endpoint_auth_method none. PKCE uses S256 only, as defined by RFC 7636, and dynamic client registration follows RFC 7591. Redirects include the RFC 9207 iss parameter.

The resulting token is audience-bound to https://app.neuron.expert/api/v1/mcp.

Consent is per scope. The business owner must tick each requested scope individually, and checkboxes start unticked. Nothing unrequested is granted. MCP OAuth can grant only read-only scopes; write scopes that exist elsewhere in the product cannot be granted to a third-party agent through MCP OAuth.

Consent pages expire in 10 minutes and authorization codes expire in 5 minutes. Access tokens last 3600 seconds. Refresh tokens last 30 days, are one-use, and rotate. Reusing a rotated refresh token after the 30-second retry window revokes the whole grant. Codes and refresh tokens are opaque and stored hashed.

Testing it with the official SDK

We test the behavior through the official TypeScript SDK, not only through direct HTTP requests.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL(issuer + "/api/v1/mcp"), { authProvider: provider });
const client = new Client({ name: "Neuron MCP native OAuth QA", version: "1.0.0" });

// Discovery is open: connect + list without a token, and OAuth has not started.
await client.connect(transport);
const catalog = await client.listTools();
expect(catalog.tools.map((t) => t.name)).toContain("neuron_inbox");
expect(authUrl).toBeUndefined();

// The first tool CALL gets 401 + WWW-Authenticate, and the SDK starts OAuth.
await expect(client.callTool({ name: "neuron_services", arguments: {} })).rejects.toThrow();
expect(authUrl?.pathname).toBe("/api/v1/oauth/authorize");
expect(authUrl?.searchParams.get("resource")).toBe(issuer + "/api/v1/mcp");
expect(verifier.length).toBeGreaterThanOrEqual(43); // PKCE verifier

A test file of 10 tests pins the public catalog behavior: initialization works without database access, tools/list returns every tool with its title, description, schema, and OAuth scheme, and the public catalog equals the authenticated full catalog without business data. It also covers ping, notifications, the public-method boundary, the tool-call challenge, and invalid-token behavior.

The SDK test covers registration, PKCE, consent for two scopes, token and refresh-token issuance, reconnecting with authorization, filtered tools/list, and a successful tool call. Another test guards the read-only boundary: every scope is read:*, every tool is annotated read-only, and the server exposes tools capability only.

In a production check on November 16, 2026, we used official MCP SDK 1.32.2 against the public endpoint. Connection and tools/list returned 10 tools without a token. A tool call was refused and OAuth started. After reviewer sign-in and consent, the authorized catalog contained the 2 approved tools. neuron_services returned 12 rows from the synthetic sandbox, and neuron_business returned the sandbox company "QA MCP Review Co".

The reviewer sandbox is a dedicated QA company with synthetic data only, including a fake 555 phone number, a .example domain, and 12 synthetic appliance-repair services. Directory reviewers use the normal consent screen.

Registry listing

The official MCP Registry listing is expert.neuron/neuron, titled "Neuron Expert", version 2.0.0, with remote type streamable-http. It includes auth: "oauth2", the 10 tools and their scopes, and publisher-provided _meta marking it read-only.

The expert.neuron namespace is proven with a DNS TXT record on neuron.expert, which covers subdomains such as app.neuron.expert. The registry listed version 2.0.0 before this discovery change.

We intentionally leave the source repository field empty because the source is private. That mcptry point remains open by design.

Results and what's next

Discovery now answers 200 without a token for initialize, ping, and tools/list. Tool calls without a token still answer 401 with OAuth metadata, and requests that send a token continue through the normal authenticated path.

The main mcptry gap around unauthenticated initialize and tools/list is now addressed; the rest remains open.

One item still needs verification: whether Claude.ai custom connectors and ChatGPT app linking start OAuth from a tool-call 401 in the same way as the official SDK. We need to connect each once to confirm that behavior. Rollback is one if in the POST /api/v1/mcp handler.

For the docs and current tool list, see Neuron Expert MCP integrations.

📰 Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.