diff --git a/.changeset/server-core-readme.md b/.changeset/server-core-readme.md
new file mode 100644
index 000000000..5b1dba53b
--- /dev/null
+++ b/.changeset/server-core-readme.md
@@ -0,0 +1,5 @@
+---
+"@voltagent/server-core": patch
+---
+
+Add README documentation
diff --git a/packages/server-core/README.md b/packages/server-core/README.md
new file mode 100644
index 000000000..53937caa6
--- /dev/null
+++ b/packages/server-core/README.md
@@ -0,0 +1,178 @@
+
+
+
+
+
+
+AI Agent Engineering Platform
+
+
+
+
+
+
+
+[](https://github.com/voltagent/voltagent/issues)
+[](https://github.com/voltagent/voltagent/pulls)
+[](https://opensource.org/licenses/MIT)
+[](https://www.npmjs.com/package/@voltagent/server-core)
+[](https://www.npmjs.com/package/@voltagent/server-core)
+[](https://s.voltagent.dev/discord)
+
+
+
+## @voltagent/server-core
+
+Framework-agnostic server core for VoltAgent. This package provides the shared infrastructure — route definitions, request handlers, WebSocket support, authentication utilities, MCP/A2A protocol helpers, and a base server provider — that all VoltAgent server adapters (e.g. `@voltagent/server-hono`) build on top of.
+
+You typically do not use this package directly. Instead, choose a server adapter for your framework (such as `@voltagent/server-hono`) and pass it to the `VoltAgent` constructor. If you are building a **custom server adapter**, this package gives you everything you need.
+
+---
+
+## Key Exports
+
+### Base Server Provider
+
+`BaseServerProvider` — Abstract class that handles the common server lifecycle (port allocation, WebSocket setup, graceful shutdown, startup banner). Extend it when building a custom adapter.
+
+```ts
+import { BaseServerProvider } from "@voltagent/server-core";
+```
+
+### Route Definitions
+
+Pre-built, framework-agnostic route metadata objects you can use to register routes in any HTTP framework:
+
+| Export | Routes covered |
+| ----------------------------- | -------------------------------------------- |
+| `AGENT_ROUTES` | Agent management and generation |
+| `WORKFLOW_ROUTES` | Workflow execute / stream / suspend / resume |
+| `TOOL_ROUTES` | Tool listing and direct execution |
+| `MEMORY_ROUTES` | Conversation and message management |
+| `LOG_ROUTES` | Log retrieval |
+| `OBSERVABILITY_ROUTES` | Traces, spans, and observability status |
+| `OBSERVABILITY_MEMORY_ROUTES` | Memory inspection for observability |
+| `MCP_ROUTES` | Model Context Protocol server endpoints |
+| `A2A_ROUTES` | Agent-to-Agent protocol endpoints |
+| `ALL_ROUTES` | All of the above combined |
+
+Helper functions: `getAllRoutesArray()`, `getRoutesByTag(tag)`.
+
+### Request Handlers
+
+Framework-agnostic handler functions. Each handler receives a `ServerProviderDeps` context and returns a serialisable response object, making them easy to wrap in any HTTP framework:
+
+- **Agent handlers** — `handleGenerateText`, `handleStreamText`, `handleChatStream`, `handleResumeChatStream`, `handleGenerateObject`, `handleStreamObject`
+- **Workflow handlers** — `handleGetWorkflows`, `handleGetWorkflow`, `handleExecuteWorkflow`, `handleStreamWorkflow`, `handleAttachWorkflowStream`, `handleSuspendWorkflow`, `handleResumeWorkflow`, `handleListWorkflowRuns`, `handleGetWorkflowState`
+- **Tool handlers** — `handleListTools`, `handleExecuteTool`
+- **Memory handlers** — `handleListMemoryConversations`, `handleCreateMemoryConversation`, `handleSaveMemoryMessages`, and more
+- **Observability handlers** — `getTracesHandler`, `getTraceByIdHandler`, `getObservabilityStatusHandler`, and more
+- **Log handlers** — `handleGetLogs`
+
+### Authentication
+
+Plug-in auth via the `AuthProvider` interface. A built-in JWT provider is included:
+
+```ts
+import { jwtAuth, createJWT } from "@voltagent/server-core";
+```
+
+### WebSocket Utilities
+
+`createWebSocketServer`, `setupWebSocketUpgrade` — set up real-time log and observability streaming over WebSocket.
+
+### MCP & A2A Protocol Helpers
+
+- `MCPServerRegistry`, `listMcpServers`, `lookupMcpServer` — register and resolve MCP servers
+- `A2AServerRegistry`, `listA2AServers`, `lookupA2AServer`, `executeA2ARequest` — Agent-to-Agent protocol support
+
+### App Setup Utilities
+
+`getOpenApiDoc`, `shouldEnableSwaggerUI`, `getOrCreateLogger`, `DEFAULT_CORS_OPTIONS` — helpers shared by all server adapters.
+
+### Edge Entry Point
+
+A lighter entry point for edge runtimes (e.g. Cloudflare Workers, Vercel Edge) is available at the `./edge` export:
+
+```ts
+import { AGENT_ROUTES, handleGenerateText } from "@voltagent/server-core/edge";
+```
+
+---
+
+## Usage Example — Custom Server Adapter
+
+The snippet below shows the minimum required to build a custom server adapter on top of `@voltagent/server-core`:
+
+```typescript
+import { createServer, type Server } from "node:http";
+import { BaseServerProvider, type ServerProviderConfig } from "@voltagent/server-core";
+import type { ServerProviderDeps } from "@voltagent/core";
+
+export class MyCustomServerProvider extends BaseServerProvider {
+ constructor(deps: ServerProviderDeps, config: ServerProviderConfig = {}) {
+ super(deps, config);
+ }
+
+ protected async startServer(port: number): Promise {
+ const server = createServer((req, res) => {
+ // Route incoming requests to the framework-agnostic handlers
+ res.writeHead(404);
+ res.end("Not found");
+ });
+
+ await new Promise((resolve) => server.listen(port, resolve));
+ return server;
+ }
+
+ protected async stopServer(): Promise {
+ await new Promise((resolve, reject) => {
+ this.server?.close((err) => (err ? reject(err) : resolve()));
+ });
+ }
+}
+
+// Factory function consumed by VoltAgent
+export function myCustomServer(config?: ServerProviderConfig) {
+ return (deps: ServerProviderDeps) => new MyCustomServerProvider(deps, config);
+}
+```
+
+Pass the factory to `VoltAgent`:
+
+```typescript
+import { VoltAgent, Agent } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+import { myCustomServer } from "./my-custom-server";
+
+const agent = new Agent({
+ name: "my-agent",
+ instructions: "A helpful assistant",
+ model: openai("gpt-4o-mini"),
+});
+
+new VoltAgent({
+ agents: { agent },
+ server: myCustomServer({ port: 3141 }),
+});
+```
+
+For a complete, production-ready server adapter see [`@voltagent/server-hono`](https://github.com/VoltAgent/voltagent/tree/main/packages/server-hono).
+
+---
+
+## Documentation
+
+- [VoltAgent Documentation](https://voltagent.dev/docs/)
+- [Agent Overview](https://voltagent.dev/docs/agents/overview/)
+- [MCP Integration](https://voltagent.dev/docs/agents/mcp/)
+
+## License
+
+Licensed under the MIT License, Copyright © 2026-present VoltAgent.