MCP Public API Reference

Use this reference to find the types and extension points for server configuration, endpoint authoring, security policy, values, subscriptions, localization, metrics, and testing. Each table links to the type's Javadoc; nested types use Java's binary-name separator, $.

Resource-not-found errors

Use this factory on McpJsonRpcError:

@NonNull
public static McpJsonRpcError fromResourceNotFound(@NonNull URI resourceUri);

@NonNull
public static McpJsonRpcError fromResourceNotFound(@NonNull URI resourceUri);

It carries canonical -32602 and data.uri; the resource-read handler boundary renders -32002 for the two supported 2025 revisions. See Resource not found.

API conventions

These conventions apply across the APIs below:

Protocol names, identifiers, descriptions, instructions and error/progress/status messages reject unpaired UTF-16 surrogates with a sanitized IllegalArgumentException during construction or the setter, before changing builder state. Valid Unicode is retained; operation-specific byte and wire-size limits still apply later.

• The transport is closed: McpServer is sealed and Soklet supplies the only implementation. Applications configure policy and handlers; they do not replace the MCP transport.
• Exported scalar fields and signatures use reference types such as Integer, Long, Boolean, and Double. Values are non-null unless an explicit nullable contract says otherwise. Public constants also use reference types. Primitive exceptions are limited to <code>void</code>, language-required annotation elements, and overrides of external Java or Servlet contracts.
• Most values and SPIs are thread-safe. Builders, McpHandlerContinuation, and exception objects are not. A handler, interceptor, limiter, admission controller, protector, publisher, listener, collector, or authorizer can be invoked concurrently unless its contract says otherwise.
• JSON values and explicitly closed decision families support exhaustive switches. Content blocks, resource contents, subscription events, operation results and observability enums are evolutionary: constants or permitted subtypes may be added in Soklet 4.x, so application switches should include a safe default. Each type's Javadoc states its policy. Request state is exposed directly through mode-specific typed accessors. McpOperationResult is sealed to its six framework-owned result families; each MCP method accepts only compatible results.
• McpOperationType is the high-level classification for application branching. The request, admission, and rate-limit contexts retain their exact JSON-RPC method strings for diagnostics, future protocol methods, and extensions; these classify as OTHER until recognized.
• The typed complete-tool DSL and advanced operation-result DSL are intentionally different. Only the advanced tool builder can declare multi-round input and return <code>input_required</code>.
• Annotation-driven and programmatic authoring are not perfectly symmetric. Review each annotation's exact elements rather than assuming every builder method is available as an annotation element.
• Soklet supplies generated schemas and keyring snapshots; applications receive these values and catch McpProtectionKeyInUseException. These types have no public constructors.
• Security defaults are deliberate: a present <code>Origin</code> is rejected when no CORS authorizer is configured; an absent <code>Origin</code> is allowed by default; Host validation is independent; unknown mirrored headers are ignored by default.
• McpServer.Builder.logRawValidatedTraceIds(Boolean) is an explicit opt-in for high-cardinality logs. Production attempts the bounded LogEventType.MCP_TRACE_CORRELATION record at admitted-request finish; the raw validated trace ID never becomes a metric dimension or framework exception field.
• Public identifiers use the compatibility spelling “Cancelation” with one <code>l</code>, as in McpMetricsEvent.CancelationSignaled.
• Simulation exercises the real request processor off-network, but does not test listener sockets, operating-system buffers, or live write-idle behavior. It does not advertise an MCP capability.
• Metric dimensions are intentionally bounded. Built-in semantic metrics do not label by principal, resource URI, mirrored-header name, trace value, argument, or result.
• The 2025 session APIs are provisional and require both server ownership/bounds and explicit endpoint revision selection. Modern and default 2025 views remain stateless. Automatic host recovery remains unverified; see session configuration.
• New CLIENT_CANCELED, SESSION_EXPIRED, and SESSION_CLOSED enum values require downstream exhaustive switches/mappings to be updated. CLIENT_CANCELED is a neutral cancelation-token category used for explicit client cancellation and for legacy session or grant retirement other than session expiry or server stop. Authorization loss, subscription lease/lifetime expiry and capacity eviction can use it; the value alone does not establish a client action. McpOperationType additionally names RESOURCES_SUBSCRIBE and RESOURCES_UNSUBSCRIBE; update exhaustive switches. Session closure and URI delivery are implemented; host-specific recovery remains unverified.
• MCP Tasks are opt-in and application-backed. McpTaskManager is the durable state and authorization authority; Soklet does not own a database, queue, worker runtime, lease, fencing, or retry system. McpInMemoryTaskManager is an explicit process-local development helper and is never the server default.

API usage

Immutable value construction

Public MCP value carriers are final immutable classes, not Java records. They have private constructors, named factories or builders, conventional get... accessors, explicit value equality, and deliberate diagnostic rendering. Scalar JSON leaves use the McpJsonString.fromValue(...), McpJsonBoolean.fromValue(...), and McpJsonNumber.fromValue(...) factories with their respective McpJsonString.getValue(), McpJsonBoolean.getValue(), and McpJsonNumber.getValue() accessors. McpInputRequest.fromDeclaration(...) pairs a declaration with parameters; declarations retain only their four method-specific factories; and prompt messages use fromUserContent(...) or fromAssistantContent(...) with getRole() and getContent().

The sealed admission, rate-limit, localization, subscription, and metrics-event roots own construction through their named static factories. Their nested variants remain public so application adapters, collectors, and tests can use typed pattern matching, but the variant constructors are private and payloads use conventional getters. The aggregate EndpointMethodKey, RequestOutcomeKey, RequestStreamTerminationKey, and SubscriptionTerminationKey types expose the exact EndpointMethodKey.fromDimensions(String, String), RequestOutcomeKey.fromDimensions(String, String, McpRequestOutcome), RequestStreamTerminationKey.fromDimensions(String, String, McpStreamTerminationReason), and SubscriptionTerminationKey.fromDimensions(String, McpStreamTerminationReason) factories, respectively, plus conventional dimension getters. McpTraceCorrelationFingerprint is different: it is a returned-only final value exposed by Soklet controls and diagnostics, with getValue() and no public creation path.

Server construction

The builder entrypoint uses a boxed port:

McpServer.Builder mcpServerBuilder =
  McpServer.withPort(Integer.valueOf(8082));

McpServer.Builder mcpServerBuilder =
  McpServer.withPort(Integer.valueOf(8082));

Apply the required policies and call build() as shown in local MCP server configuration or the production example. The resulting server always uses a dedicated listener.

The builder discovers its endpoint registry from generated classpath metadata and accepts requests anonymously by default. endpointRegistry(...) and admissionController(...) override those defaults; passing null to either setter restores its default. Tool rate limiting is optional. A configured limiter resolves in tool, endpoint, then server-fallback order. A tool with no resolved limiter has no tool rate quota; transport and execution bounds remain in effect.

For annotated endpoints, McpEndpointRegistry supports immutable withSkillRegistrations(...) and withSkillGroups(...) copies selected by the exact annotated class. Each replaces its complete list (empty clears), preserves the other list and generated handlers, and validates the result. See the Skills composition examples.

allowedHosts(Set<String>) accepts hostname-only values. Explicitly allowed names accept a valid public port or an omitted port; automatic loopback aliases still require the listener port. Configured mirrored-header-name diagnostics can expose only bounded, sanitized header names; header values are never logged.

Endpoint and handler construction

Client McpImplementation name/version strings may be blank and are preserved exactly. Endpoint server information requires nonblank name/version strings.

Endpoint paths are normalized, absolute, non-root paths with no query or fragment. Each registry must contain at least one endpoint, and normalized endpoint paths must be unique. Within an endpoint, tool names, prompt names, exact resource URIs, and resource-template strings are independently unique.

The principal application handler signatures are shown here as owner-qualified signature notation:

McpOperationResult McpToolHandler<A>.handle(
  McpRequestContext requestContext,
  McpToolArguments<A> toolArguments,
  McpInvocationFeatures invocationFeatures
) throws Exception;

R McpCompleteToolHandler<A, R>.handle(
  McpRequestContext requestContext,
  McpToolArguments<A> toolArguments,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpOperationResult McpPromptHandler.handle(
  McpRequestContext requestContext,
  McpPromptGetContext promptGetContext,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpOperationResult McpResourceReadHandler.handle(
  McpRequestContext requestContext,
  McpResourceReadContext resourceReadContext,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpResourcePage McpResourceListHandler.handle(
  McpRequestContext requestContext,
  McpResourceListContext resourceListContext,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpOperationResult McpToolHandler<A>.handle(
  McpRequestContext requestContext,
  McpToolArguments<A> toolArguments,
  McpInvocationFeatures invocationFeatures
) throws Exception;

R McpCompleteToolHandler<A, R>.handle(
  McpRequestContext requestContext,
  McpToolArguments<A> toolArguments,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpOperationResult McpPromptHandler.handle(
  McpRequestContext requestContext,
  McpPromptGetContext promptGetContext,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpOperationResult McpResourceReadHandler.handle(
  McpRequestContext requestContext,
  McpResourceReadContext resourceReadContext,
  McpInvocationFeatures invocationFeatures
) throws Exception;

McpResourcePage McpResourceListHandler.handle(
  McpRequestContext requestContext,
  McpResourceListContext resourceListContext,
  McpInvocationFeatures invocationFeatures
) throws Exception;

Handlers and extension points must be safe for concurrent invocation. McpInvocationFeatures performs exact-class lookup, not assignable-type lookup. A supplied McpHandlerContinuation is synchronous, thread-bound, and one-shot; it cannot be retained or have proceed() called more than once.

Tool registration stages

McpToolRegistration.withName(String, Set<McpProtocolVersion>) begins a staged DSL with an explicitly selected, nonempty set of exact protocol revisions:

• argumentAndOutputTypes(Class, Class), argumentAndOutputTypes(Class, TypeReference), argumentAndOutputTypes(TypeReference, Class), and argumentAndOutputTypes(TypeReference, TypeReference) select typed arguments and typed complete results.
• argumentType(Class) and argumentType(TypeReference) select typed arguments with an advanced McpToolHandler result.
• jsonObjectArguments() selects an immutable McpJsonObject argument and a fixed object input schema.
• inputSchema(McpJsonObject) selects validated immutable JSON-object arguments under an application-authored Profile 1 object-root input schema.
• CompleteBuilder configures a typed complete result and deliberately has no equivalents of OperationBuilder.inputRequestDeclarations(List) or OperationBuilder.requestStateMode(McpRequestStateMode).
• OperationBuilder configures the advanced result path and may return a compatible McpCompleteResult or McpInputRequiredResult.

Tool names are 1–128 characters from <code>A-Z</code>, <code>a-z</code>, <code>0-9</code>, underscore, hyphen, and dot. McpToolSchema exposes a derived, fixed, or application-authored input Profile 1 document for inspection. Applications may submit an authored object-root input document through inputSchema(...), but cannot construct or replace McpToolSchema directly or author an output schema.

Multi-round input and state

An operation must declare every client request it may initiate. The supported declarations are form and URL modes of <code>elicitation/create</code>, with the matching capability derived by McpInputRequestDeclaration. A returned McpInputRequiredResult must contain at least one keyed input request, request state, or both.

Framework-protected state carries application JSON and is authenticated, operation-bound, authorization-bound, expiring, and round-limited. Application-protected state is an opaque nonempty string that Soklet passes through while the application independently owns protection, expiry, and validation. A custom McpRequestStateProtector is an alternative provider for framework-protected state, not the owner of McpRequestStateMode.APPLICATION_PROTECTED values. Request contexts and input-required results expose state through separate typed optional accessors; Soklet-owned logs and diagnostics continue to redact it. Input parameters and resource-update values retain their data-minimizing public renderings.

Durable MCP Tasks

McpServer.Builder.taskManager(McpTaskManager) opts a server into MCP Tasks; a missing manager means the server does not advertise or accept Tasks. A task-capable invocation exposes McpTaskCreationContext, whose getTaskOrigin() value must be persisted atomically with the application's work description before the handler returns McpTaskCreatedResult. Soklet later uses that opaque, non-wire origin to recover the original operation and enforce its result contract; it is not an authorization grant.

McpTaskManager remains authoritative for task state, retention, authorization, input-response idempotency, and durable cancelation intent. Every protocol lookup or mutation is independently admitted, then the manager must atomically authorize it against the task's application-owned binding. Unknown and unauthorized IDs are deliberately indistinguishable. Polling through <code>tasks/get</code> is authoritative; an optional McpTaskEventPublisher broadcasts task-ID-only hints, after which Soklet performs a fresh authorized lookup before emitting a notification.

McpTaskManager.fromInMemoryDefaults() and McpInMemoryTaskManager.builder() provide a bounded process-local implementation for tests, simulation, development, and deliberately ephemeral single-process applications. It has no durable persistence, shared-node coordination, work queue, worker, leases, fencing, retry, or crash recovery, and the server never selects it implicitly. See MCP Tasks for the wire lifecycle and production ownership model.

Progress, subscriptions, and resources

Progress reporting is conditional on the request's progress token. Accepted progress values must increase; an equal value is coalesced, a decrease throws while active, and reporting after cancelation or completion has no effect. Reporting is synchronous and can block on the bounded stream queue.

Subscription publishers broadcast only coarse resource-list changes and resource-URI updates. Soklet, not the publisher, owns authorization filtering, requested-URI filtering, coalescing, per-stream queues, backpressure, and wire encoding. Publisher registration close is idempotent, although a delivery already selected or in flight may finish.

A custom resource-list handler is the sole authority for its page; Soklet does not merge static registrations into the returned page. A page may be empty and an empty next cursor remains present. A successful resource read output must contain at least one content value. Exact registrations may declare a fixed size; template registrations deliberately cannot.

Diagnostics, tracing, simulation, and metrics

McpServer.getDiagnostics() returns an immutable McpServerDiagnostics snapshot. Lifecycle, capacity, handler, queue, stream, and subscription values form one runtime snapshot; protection and trace values form a separate security-control snapshot. There is no global linearization point spanning both domains. The invariant <code>0 <= activeSubscriptions <= activeRequestStreams</code> holds.

Trace-correlation keys use a 1–64-byte ASCII HTTP-token ID and at least 32 secret bytes. Key material is copied and never exposed. Rotation replaces one active key; no public historical-key or historical-token facility exists. Configuration fingerprints are operational comparison values, not authentication or token-derivation inputs.

Simulation response and completion reads are repeatable; successful stream-item reads are destructive. Defaults are 128 pending SSE items and 10 MiB of cumulative captured bytes. Consuming an item releases an item slot but never refunds captured bytes. Completion throwables retain exact application identities and may contain secrets, so callers own disclosure decisions.

Subscription-maintenance counts are available through McpMetricsSnapshot.getSubscriptionMaintenance() and McpMetricsSnapshot.Builder.subscriptionMaintenance(Map<SubscriptionMaintenanceKey, Long>) plus the nested immutable SubscriptionMaintenanceKey: its static fromDimensions(String endpointPath, McpMetricsEvent.SubscriptionMaintenance.Work maintenanceWork, McpMetricsEvent.SubscriptionMaintenance.Outcome maintenanceOutcome) factory, getEndpointPath(), getWork(), getOutcome(), equals(Object), hashCode() and toString(). The map's getter is nonnull; the builder accepts a nullable map with nonnull keys and boxed nonnull Long counts. The key factory/getters return nonnull values, factory parameters are nonnull, and equality accepts a nullable Object. Events expose only dimensions meaningful to each transition, and the aggregate snapshot uses final fixed-dimension key classes for endpoint, bounded method, outcome, and termination reason. The public McpMetricsEvent.protocolError(code) factory checks non-nullity, not the runtime's current fixed-code allowlist; do not treat an arbitrary application-created event as proof a code can be emitted by Soklet. McpMetricsEvent.CancelationSignaled intentionally has no reason field; bounded reasons remain on the cooperative token and cancelation exception with no framework cause.

API types by area

Server, endpoint, and discovery

Annotation-driven authoring

Admission control and transport policy

Rate limiting

Request context, results, interception, and errors

Tools and schemas

Prompts

Argument completion

Resources, listing, and caching

Skills

Content and presentation metadata

Apps metadata

Immutable JSON values

Multi-round input and request state

Progress

Request-state protection

Resource subscriptions

Durable Tasks

2025 sessions and HTTP admission

Localization

Diagnostics

Trace-correlation control

Off-network simulation

Semantic metric events

Aggregate semantic metrics

Terminal vocabularies

Shared Soklet APIs

Referenced shared APIs

ShutdownComponentType.MCP identifies the MCP lifecycle component. SimulatorConfig.Builder.configureMcpServer(Consumer) customizes the MCP server used for simulation. MCP lifecycle callbacks carry shared ShutdownComponentResult and ShutdownComponentDisposition values.

MCP handlers and annotation injection also use established Soklet and JDK types:

• Request and HttpMethod represent the underlying HTTP request and construct simulator input.
• CancelationToken is the cooperative signal available through invocation features or annotated handler injection.
• TraceContext represents validated MCP distributed trace propagation.
• InstanceProvider controls annotated endpoint-instance acquisition.
• TypeReference<T> preserves nested generic argument/result types and typed input-response lookups.
• BearerAuthenticationChallenge builds validated RFC 6750 Bearer challenges and exposes their header value; BearerAuthenticationError supplies the standard error values. MCP admission can attach the challenge as WWW-Authenticate; see OAuth.
• Cors, CorsPreflight, CorsResponse, and CorsPreflightResponse are shared Origin-policy values used by CorsAuthorizer.
• MetricsCollector.HistogramSnapshot and MetricsCollector.TransportFailureReason represent histogram data and bounded transport-failure categories in metric aggregates and events.
• JDK types such as URI, Duration, Instant, Optional, collections, ExecutorService, and Throwable retain their ordinary contracts.

When using these dependencies, a sensitive Throwable, mutable principal, or application-context object retains its own disclosure and thread-safety risks when carried through an otherwise immutable MCP value.

Construction and extension boundaries

Related guides

For task-oriented explanations, continue with Endpoint Authoring, Tools and Schemas, Prompts and Resources, Input and Request State, Progress and Subscriptions, MCP Tasks, Security and Policy, Server Configuration, Observability and Testing, and Localization.

Transport streaming completion preparation

LifecycleObserver.willWriteResponseStream(StreamingResponseHandle) and MetricsCollector.willWriteResponseStream(StreamingResponseHandle) are default methods that declare the transport's guarantee of a later termination callback. See Custom HTTP streaming completion for callback order and decorator forwarding.