Skip to content

Commit bc2adce

Browse files
technicalpicklestechnicalpickles
committed
docs: add specification for MCP direct endpoint
Related smart-mcp-proxy#279 Adds feature specification for a new `/mcp/direct` endpoint that exposes all upstream MCP tools directly alongside internal MCPProxy tools. This spec documents the design decisions, user stories, functional requirements, and success criteria for the feature. Implementation will follow in subsequent commits. ## Key Design Decisions - Config flag `enable_direct_endpoint` (default: false, opt-in) - Quarantined/disabled/disconnected servers excluded - Tool annotations preserved from upstream - Upstream tools namespaced as `server:tool` ## Spec Contents - 5 prioritized user stories (P1-P3) - 15 functional requirements - 5 measurable success criteria - Edge cases and assumptions documented
1 parent 6b13013 commit bc2adce

2 files changed

Lines changed: 238 additions & 0 deletions

File tree

‎specs/025-mcp-direct-endpoint/checklists/requirements.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Specification Quality Checklist: MCP Direct Endpoint
2+
3+
**Purpose**: Validate specification completeness and quality before proceeding to planning
4+
**Created**: 2026-01-26
5+
**Feature**: [spec.md](../spec.md)
6+
7+
## Content Quality
8+
9+
- [x] No implementation details (languages, frameworks, APIs)
10+
- [x] Focused on user value and business needs
11+
- [x] Written for non-technical stakeholders
12+
- [x] All mandatory sections completed
13+
14+
## Requirement Completeness
15+
16+
- [x] No [NEEDS CLARIFICATION] markers remain
17+
- [x] Requirements are testable and unambiguous
18+
- [x] Success criteria are measurable
19+
- [x] Success criteria are technology-agnostic (no implementation details)
20+
- [x] All acceptance scenarios are defined
21+
- [x] Edge cases are identified
22+
- [x] Scope is clearly bounded
23+
- [x] Dependencies and assumptions identified
24+
25+
## Feature Readiness
26+
27+
- [x] All functional requirements have clear acceptance criteria
28+
- [x] User scenarios cover primary flows
29+
- [x] Feature meets measurable outcomes defined in Success Criteria
30+
- [x] No implementation details leak into specification
31+
32+
## Notes
33+
34+
- All items pass validation
35+
- Spec is ready for `/speckit.clarify` or `/speckit.plan`
36+
- Design decisions from conversation captured in spec:
37+
- Config flag `enable_direct_endpoint` defaults to `false` (opt-in)
38+
- Quarantined servers excluded
39+
- Tool annotations preserved from upstream

‎specs/025-mcp-direct-endpoint/spec.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Feature Specification: MCP Direct Endpoint
2+
3+
**Feature Branch**: `025-mcp-direct-endpoint`
4+
**Created**: 2026-01-26
5+
**Status**: Draft
6+
**Input**: User description: "Add MCP direct endpoint to expose all proxied tools directly alongside internal tools, with server:tool namespacing for upstream tools"
7+
**Related Issue**: https://github.com/smart-mcp-proxy/mcpproxy-go/issues/279
8+
9+
## Problem Statement
10+
11+
Currently, MCPProxy exposes tools through a search-first workflow:
12+
1. Clients call `retrieve_tools` to search for tools
13+
2. Clients call `call_tool_read/write/destructive` with `server:tool` format
14+
15+
This workflow provides significant token savings (~99%) for large tool sets. However, some clients and use cases need direct access to all tools without the search intermediary, especially as AI platforms adopt built-in tool search capabilities (per Anthropic's "Advanced Tool Use" announcement).
16+
17+
## User Scenarios & Testing *(mandatory)*
18+
19+
### User Story 1 - Direct Tool Access (Priority: P1)
20+
21+
As an MCP client user, I want to connect to a single endpoint that exposes all available tools directly, so I can use any tool without first searching for it.
22+
23+
**Why this priority**: This is the core value proposition - enabling direct tool access for clients that don't need the search-first workflow.
24+
25+
**Independent Test**: Can be fully tested by connecting an MCP client to the `/mcp/direct` endpoint and verifying all upstream tools appear in the tools/list response alongside internal tools.
26+
27+
**Acceptance Scenarios**:
28+
29+
1. **Given** the direct endpoint is enabled and upstream servers are connected, **When** a client requests the tools list from `/mcp/direct`, **Then** the response includes all tools from connected upstream servers with `server:tool` naming format.
30+
31+
2. **Given** the direct endpoint is enabled, **When** a client requests the tools list, **Then** the response includes all internal MCPProxy tools (retrieve_tools, call_tool_*, upstream_servers, etc.) without a server prefix.
32+
33+
3. **Given** the direct endpoint is enabled and a tool exists as `github:create_issue`, **When** a client calls this tool directly, **Then** the call is routed to the github upstream server and executed successfully.
34+
35+
---
36+
37+
### User Story 2 - Configuration Toggle (Priority: P1)
38+
39+
As a system administrator, I want to enable or disable the direct endpoint via configuration, so I can choose whether to expose all tools directly or require the search-first workflow.
40+
41+
**Why this priority**: Essential for deployment flexibility - some environments want search-first (token savings), others want direct access.
42+
43+
**Independent Test**: Can be tested by toggling the configuration flag and verifying the endpoint availability changes accordingly.
44+
45+
**Acceptance Scenarios**:
46+
47+
1. **Given** the configuration option `enable_direct_endpoint` is set to `true`, **When** the server starts, **Then** the `/mcp/direct` endpoint is available and functional.
48+
49+
2. **Given** the configuration option `enable_direct_endpoint` is set to `false` (or not set), **When** a client attempts to access `/mcp/direct`, **Then** the endpoint is not available (returns 404).
50+
51+
3. **Given** the direct endpoint is enabled, **When** viewing server status or logs, **Then** the system indicates the direct endpoint is active.
52+
53+
---
54+
55+
### User Story 3 - Security Exclusions (Priority: P2)
56+
57+
As a security-conscious administrator, I want quarantined servers' tools excluded from the direct endpoint, so I don't accidentally expose unapproved tools to clients.
58+
59+
**Why this priority**: Important for security, but secondary to core functionality since quarantine is an existing security feature.
60+
61+
**Independent Test**: Can be tested by quarantining a server and verifying its tools disappear from the direct endpoint's tool list.
62+
63+
**Acceptance Scenarios**:
64+
65+
1. **Given** a server is quarantined, **When** a client requests the tools list from `/mcp/direct`, **Then** tools from the quarantined server are not included in the response.
66+
67+
2. **Given** a server is disabled, **When** a client requests the tools list from `/mcp/direct`, **Then** tools from the disabled server are not included in the response.
68+
69+
3. **Given** a server is disconnected, **When** a client requests the tools list from `/mcp/direct`, **Then** tools from the disconnected server are not included in the response.
70+
71+
---
72+
73+
### User Story 4 - Dynamic Tool Synchronization (Priority: P2)
74+
75+
As an MCP client user, I want the direct endpoint's tool list to update automatically when upstream servers connect or disconnect, so I always see the current available tools.
76+
77+
**Why this priority**: Important for reliability but secondary to initial tool exposure.
78+
79+
**Independent Test**: Can be tested by connecting/disconnecting an upstream server and observing the tool list update on the direct endpoint.
80+
81+
**Acceptance Scenarios**:
82+
83+
1. **Given** the direct endpoint is active and an upstream server connects, **When** the server's tools become available, **Then** the direct endpoint's tool list is updated to include the new tools.
84+
85+
2. **Given** the direct endpoint is active and an upstream server disconnects, **When** the server becomes unavailable, **Then** the direct endpoint's tool list is updated to remove the server's tools.
86+
87+
3. **Given** the direct endpoint is active, **When** an upstream server's tools change (via tools/list_changed notification), **Then** the direct endpoint's tool list reflects the changes.
88+
89+
---
90+
91+
### User Story 5 - Tool Annotation Preservation (Priority: P3)
92+
93+
As an MCP client developer, I want upstream tool annotations (readOnlyHint, destructiveHint, etc.) preserved on the direct endpoint, so my client can make informed decisions about tool behavior.
94+
95+
**Why this priority**: Nice-to-have for client intelligence but not critical for basic functionality.
96+
97+
**Independent Test**: Can be tested by verifying tool annotations from upstream servers appear correctly on tools retrieved from the direct endpoint.
98+
99+
**Acceptance Scenarios**:
100+
101+
1. **Given** an upstream tool has `readOnlyHint: true` annotation, **When** the tool is listed on the direct endpoint, **Then** the annotation is preserved in the tool definition.
102+
103+
2. **Given** an upstream tool has `destructiveHint: true` annotation, **When** the tool is listed on the direct endpoint, **Then** the annotation is preserved in the tool definition.
104+
105+
---
106+
107+
### Edge Cases
108+
109+
- What happens when all upstream servers are disabled or quarantined? → Only internal tools are listed
110+
- What happens when two upstream servers have tools with the same name? → They're disambiguated by server prefix (e.g., `serverA:read_file` vs `serverB:read_file`)
111+
- What happens if an upstream server provides a tool named like an internal tool? → Server-prefixed name prevents collision (e.g., `myserver:retrieve_tools` vs `retrieve_tools`)
112+
- How does the system handle rapid connect/disconnect cycles? → Tool list updates atomically on each state change
113+
114+
## Requirements *(mandatory)*
115+
116+
### Functional Requirements
117+
118+
- **FR-001**: System MUST provide a new MCP endpoint at `/mcp/direct` when the feature is enabled
119+
- **FR-002**: System MUST expose all tools from connected, enabled, non-quarantined upstream servers on the direct endpoint
120+
- **FR-003**: System MUST expose all internal MCPProxy tools (retrieve_tools, call_tool_read, call_tool_write, call_tool_destructive, upstream_servers, quarantine_security, read_cache, code_execution, list_registries, search_servers) on the direct endpoint
121+
- **FR-004**: System MUST namespace upstream tools using `server:tool` format to prevent collisions
122+
- **FR-005**: System MUST NOT namespace internal tools (they appear without prefix)
123+
- **FR-006**: System MUST exclude tools from quarantined servers
124+
- **FR-007**: System MUST exclude tools from disabled servers
125+
- **FR-008**: System MUST exclude tools from disconnected servers
126+
- **FR-009**: System MUST synchronize the tool list when upstream server state changes (connect, disconnect, quarantine, enable/disable)
127+
- **FR-010**: System MUST preserve tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title) from upstream servers
128+
- **FR-011**: System MUST route tool calls to the appropriate upstream server based on the server prefix
129+
- **FR-012**: System MUST handle internal tool calls by delegating to existing handler logic
130+
- **FR-013**: System MUST provide a configuration option `enable_direct_endpoint` to enable/disable this feature
131+
- **FR-014**: System MUST default the `enable_direct_endpoint` configuration to `false` (opt-in)
132+
- **FR-015**: System MUST return 404 for `/mcp/direct` when the feature is disabled
133+
134+
### Key Entities
135+
136+
- **DirectMCPServer**: A separate MCP server instance that manages the direct endpoint, distinct from the search-based MCPProxyServer
137+
- **Tool Namespace**: The `server:tool` naming convention that maps upstream tools to their source server
138+
- **Tool Synchronization**: The mechanism that keeps the direct endpoint's tool list in sync with upstream server state
139+
140+
## Success Criteria *(mandatory)*
141+
142+
### Measurable Outcomes
143+
144+
- **SC-001**: Clients connecting to `/mcp/direct` receive a complete tool list within 500ms of connection
145+
- **SC-002**: Tool list updates reflect upstream server changes within 2 seconds of state change
146+
- **SC-003**: 100% of upstream tool calls through the direct endpoint succeed when the upstream server is healthy
147+
- **SC-004**: Tool annotations are preserved with 100% fidelity from upstream to direct endpoint
148+
- **SC-005**: Zero tools from quarantined/disabled/disconnected servers appear in the direct endpoint's tool list
149+
150+
## Assumptions
151+
152+
- The existing `EventTypeServersChanged` event provides sufficient notification for tool synchronization
153+
- The `StateView` contains cached tool information suitable for rebuilding the tool list
154+
- The `mcp-go` library's `SetTools()` method provides atomic tool list replacement
155+
- Internal tool handlers can be shared between the existing MCPProxyServer and the new DirectMCPServer
156+
157+
## Out of Scope
158+
159+
- Changing the behavior of the existing `/mcp` endpoint
160+
- Per-server or per-tool filtering on the direct endpoint (all-or-nothing exposure)
161+
- Session sharing between `/mcp` and `/mcp/direct` endpoints
162+
- WebUI integration for the direct endpoint
163+
164+
## Commit Message Conventions *(mandatory)*
165+
166+
When committing changes for this feature, follow these guidelines:
167+
168+
### Issue References
169+
- ✅ **Use**: `Related #279` - Links the commit to the issue without auto-closing
170+
- ❌ **Do NOT use**: `Fixes #279`, `Closes #279`, `Resolves #279` - These auto-close issues on merge
171+
172+
**Rationale**: Issues should only be closed manually after verification and testing in production, not automatically on merge.
173+
174+
### Co-Authorship
175+
- ❌ **Do NOT include**: `Co-Authored-By: Claude <noreply@anthropic.com>`
176+
- ❌ **Do NOT include**: "🤖 Generated with [Claude Code](https://claude.com/claude-code)"
177+
178+
**Rationale**: Commit authorship should reflect the human contributors, not the AI tools used.
179+
180+
### Example Commit Message
181+
```
182+
feat: add MCP direct endpoint for all-tools exposure
183+
184+
Related #279
185+
186+
Adds a new /mcp/direct endpoint that exposes all upstream tools directly
187+
alongside internal MCPProxy tools, enabling clients to use tools without
188+
the search-first workflow.
189+
190+
## Changes
191+
- Add EnableDirectEndpoint config option (default: false)
192+
- Create DirectMCPServer with tool synchronization
193+
- Register internal tools and upstream tools with server:tool namespacing
194+
- Mount endpoint at /mcp/direct when enabled
195+
196+
## Testing
197+
- E2E tests for tool listing and calling
198+
- Unit tests for tool synchronization logic
199+
```

0 commit comments

Comments
 (0)