1# Architecture
2 
3Understanding how mcp-use servers are structured under the hood.
4 
5---
6 
7## Server Structure
8 
9mcp-use is **built on top of the Hono web framework**. When you create an `MCPServer`, you get:
10 
11```typescript
12const server = new MCPServer({
13  name: "my-server",
14  version: "1.0.0"
15});
16```
17 
18The server instance has three key components:
19 
20### 1. `server.app` - Hono Instance
21 
22The underlying Hono web application that handles HTTP routing and middleware.
23 
24```typescript
25// Add custom HTTP routes
26server.get('/health', (c) => c.json({ status: 'ok' }));
27 
28// Add Hono middleware
29server.use(async (c, next) => {
30  console.log(`Request: ${c.req.method} ${c.req.url}`);
31  await next();
32});
33```
34 
35**Use for:**
36- Custom HTTP endpoints
37- Hono-specific middleware
38- Direct access to Hono features
39 
40### 2. `server.nativeServer` - MCP SDK
41 
42The official MCP protocol server from `@modelcontextprotocol/sdk`.
43 
44```typescript
45// Access native MCP SDK methods (advanced)
46server.nativeServer.server.setRequestHandler(...);
47```
48 
49**Use for:**
50- Advanced MCP protocol features
51- Direct SDK access (rare)
52 
53### 3. MCP Server Methods
54 
55High-level methods for defining MCP primitives:
56 
57```typescript
58server.tool({ ... }, async (input) => { ... });
59server.resource({ ... }, async () => { ... });
60server.prompt({ ... }, async (input) => { ... });
61server.proxy({ child: { url: "..." } });
62```
63 
64---
65 
66## Middleware System
67 
68mcp-use supports two kinds of middleware registered via `server.use()`:
69 
701. **HTTP middleware** — intercepts HTTP requests (Hono layer)
712. **MCP middleware** — intercepts MCP operations like tool calls, resource reads, etc.
72 
73The `mcp:` prefix in the pattern string distinguishes them:
74 
75```typescript
76// MCP middleware — fires when MCP operations occur
77server.use("mcp:tools/call", async (ctx, next) => { ... });
78 
79// HTTP middleware — fires on every HTTP request (no mcp: prefix)
80server.use(async (c, next) => { ... });
81```
82 
83### MCP Middleware
84 
85MCP middleware intercepts operations at the protocol level, after HTTP routing. It is ideal for cross-cutting concerns like logging, authentication, rate limiting, and tool filtering.
86 
87```typescript
88// Catch-all: every MCP operation
89server.use("mcp:*", async (ctx, next) => {
90  const start = Date.now();
91  const result = await next();
92  console.log(`${ctx.method} — ${Date.now() - start}ms`);
93  return result;
94});
95 
96// Specific operation
97server.use("mcp:tools/call", async (ctx, next) => {
98  if (!ctx.auth?.scopes.includes("tools:call")) {
99    throw new Error("Insufficient scope");
100  }
101  return next();
102});
103 
104// Namespace wildcard
105server.use("mcp:tools/*", async (ctx, next) => {
106  console.log(`Tool operation: ${ctx.method}`);
107  return next();
108});
109```
110 
111**Pattern matching:**
112 
113| Pattern | Matches |
114|---------|---------|
115| `mcp:*` | Every MCP operation |
116| `mcp:tools/*` | All tool operations |
117| `mcp:tools/call` | Tool calls only |
118| `mcp:resources/*` | All resource operations |
119| `mcp:prompts/*` | All prompt operations |
120 
121**`MiddlewareContext` fields:**
122 
123| Field | Description |
124|-------|-------------|
125| `ctx.method` | MCP method name (e.g. `"tools/call"`) |
126| `ctx.params` | Request params — mutable |
127| `ctx.session` | Session ID when available |
128| `ctx.auth` | OAuth info (scopes, permissions, user) when OAuth is configured |
129| `ctx.state` | `Map` for passing data across middleware in the same request |
130 
131### HTTP Middleware
132 
133mcp-use uses **Hono's middleware system** for HTTP middleware. Both Hono and Express middleware are supported.
134 
135```typescript
136// ✅ Hono style
137server.use(async (c, next) => {
138  // c = Hono Context object
139  await next();
140});
141 
142// ✅ Express style (auto-adapted)
143import morgan from "morgan";
144server.use(morgan("combined"));
145```
146 
147#### Hono-Compatible Middleware
148 
149```typescript
150import { rateLimiter } from "hono-rate-limiter";
151 
152server.use(rateLimiter({
153  windowMs: 15 * 60 * 1000,
154  limit: 100,
155  keyGenerator: (c) =>
156    c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? "unknown",
157}));
158```
159 
160#### Express Middleware (Auto-Adapted)
161 
162```typescript
163import rateLimit from "express-rate-limit";
164 
165server.use("/api", rateLimit({
166  windowMs: 15 * 60 * 1000,
167  max: 100,
168}));
169```
170 
171---
172 
173## server.use() routing
174 
175`server.use()` handles three kinds of middleware depending on the first argument:
176 
177```typescript
178// MCP middleware (mcp: prefix) — intercepts MCP operations
179server.use("mcp:tools/call", async (ctx, next) => { ... });
180server.use("mcp:*",          async (ctx, next) => { ... });
181 
182// HTTP middleware with path (leading /) — Hono path-scoped middleware
183server.use("/api/*", someHttpMiddleware);
184 
185// HTTP middleware without path — Hono catch-all
186server.use(async (c, next) => { ... });
187```
188 
189`server.app.use()` always routes to Hono and never to MCP middleware:
190 
191```typescript
192// Always Hono, never MCP
193server.app.use(async (c, next) => { ... });
194```
195 
196**In practice:** Use `server.use("mcp:...", handler)` for MCP middleware and `server.use(handler)` or `server.app.use(handler)` for HTTP middleware.
197 
198---
199 
200## Request Lifecycle
201 
202Understanding the flow of a request:
203 
204```
2051. HTTP Request arrives
206   ↓
2072. Hono middleware chain (server.use without mcp: prefix)
208   ↓
2093. OAuth bearer auth (if `oauth` is configured — verifies JWT, populates ctx.auth)
210   ↓
2114. MCP protocol routing
212   ↓
2135. MCP middleware chain (server.use('mcp:...') handlers)
214   ↓
2156. Tool/Resource/Prompt handler
216   ↓
2177. Response helpers (text, object, etc.)
218   ↓
2198. MCP protocol response
220   ↓
2219. HTTP Response
222```
223 
224> When `oauth` is configured, unauthenticated requests to `/mcp/*` receive a `401` with a `WWW-Authenticate` header that tells MCP clients where to start the OAuth flow. See [../authentication/overview.md](../authentication/overview.md) for setup.
225 
226### Example Flow
227 
228```typescript
229server.app.use(async (c, next) => {
230  console.log("1. Middleware start");
231  await next();
232  console.log("5. Middleware end");
233});
234 
235server.tool(
236  { name: "greet", schema: z.object({ name: z.string() }) },
237  async ({ name }) => {
238    console.log("3. Tool handler");
239    return text(`Hello, ${name}`); // 4. Response helper
240  }
241);
242```
243 
244---
245 
246## Custom HTTP Endpoints
247 
248You can mix MCP tools with custom HTTP routes:
249 
250```typescript
251// MCP tool (called via MCP protocol)
252server.tool({ name: "calculate", ... }, async (input) => { ... });
253 
254// Custom HTTP endpoint (called via HTTP)
255server.app.get('/api/status', (c) => {
256  return c.json({
257    uptime: process.uptime(),
258    tools: server.registeredTools.length
259  });
260});
261 
262// Both coexist on the same server
263```
264 
265**Use cases:**
266- Health check endpoints
267- Webhooks
268- Admin APIs
269- Public data endpoints
270 
271---
272 
273## Common Patterns
274 
275### Logging Middleware
276 
277```typescript
278server.use(async (c, next) => {
279  const start = Date.now();
280  await next();
281  const duration = Date.now() - start;
282  console.log(`${c.req.method} ${c.req.path} - ${duration}ms`);
283});
284```
285 
286### Error Handling
287 
288```typescript
289server.use(async (c, next) => {
290  try {
291    await next();
292  } catch (err) {
293    console.error("Server error:", err);
294    return c.json({ error: "Internal server error" }, 500);
295  }
296});
297```
298 
299---
300 
301## Best Practices
302 
303### 1. Use Hono-Compatible Middleware Packages
304```typescript
305✅ import { rateLimiter } from "hono-rate-limiter";
306✅ server.use(rateLimiter({ ... }));
307 
308❌ Writing custom rate limiting logic
309```
310 
311### 2. Understand the Signature
312```typescript
313✅ server.use(async (c, next) => { ... });
314 
315❌ server.use((req, res, next) => { ... }); // Express style
316```
317 
318### 3. Access Hono When Needed
319```typescript
320✅ server.app.get('/custom', (c) => c.json({ ... }));
321 
322❌ Trying to add routes via server.get() // Doesn't exist
323```
324 
325### 4. Keep MCP Separate from HTTP
326```typescript
327✅ MCP tools for AI interactions
328✅ HTTP routes for webhooks/admin
329✅ Both on same server
330 
331❌ Mixing concerns in tool handlers
332```
333 
334---
335 
336## Key Takeaways
337 
338- **Built on Hono** - mcp-use wraps the Hono web framework
339- **Two middleware layers** - HTTP (Hono) layer and MCP operation layer
340- **`mcp:` prefix** - Use `server.use('mcp:tools/call', handler)` for MCP middleware; no prefix = HTTP middleware
341- **Hono style** - HTTP middleware uses `(c, next) => ...` signature
342- **Two access points** - `server.use()` and `server.app.use()` both work for HTTP
343 
344---
345 
346## Next Steps
347 
348- **Build tools** → [../server/tools.md](../server/tools.md)
349- **Add resources** → [../server/resources.md](../server/resources.md)
350- **Understand primitives** → [concepts.md](concepts.md)
351