---
title: "MCP Completions Server - Simple Learning Demo"
source: Panaversity Learn Agentic AI
source_url: https://github.com/panaversity/learn-agentic-ai
licence: Apache-2.0
domain: agentic-ai
subdomain: panaversity-agentic
date_added: 2026-04-25
---

# MCP Completions Server - Simple Learning Demo

A simplified MCP completions implementation for learning core concepts with streamable HTTP endpoints and Postman testing.

## 🚀 Quick Start

### 1. Start the Server
```bash
uv run server.py
```
Server runs on `http://localhost:8000`

### 2. Test with HTTP Client
```bash
# In a new terminal
uv run client.py
```

### 3. Test with Postman
Import `postman/MCP_Completions_Server.postman_collection.json` and test HTTP endpoints.

## 📁 Files

- `server.py` - Simplified FastMCP server with completions (~100 lines)
- `client.py` - HTTP completion testing client (~80 lines)  
- `postman/` - Postman collection for HTTP testing
- `pyproject.toml` - UV project configuration

## 🎯 What You'll Learn

### 1. Basic Completions
**Concept**: Auto-complete prompt arguments and resource parameters
```python
# Language completion: "py" → ["python"]
@mcp.completion()
async def handle_completion(ref, argument, context):
    if argument.name == "language":
        matches = [lang for lang in LANGUAGES if lang.startswith(argument.value)]
        return Completion(values=matches, hasMore=False)
```

### 2. Context-Aware Completions  
**Concept**: Suggestions change based on other resolved parameters
```python
# Framework completion based on language context
if argument.name == "framework" and context:
    language = context.arguments.get("language")
    frameworks = FRAMEWORKS.get(language, [])
    matches = [fw for fw in frameworks if fw.startswith(argument.value)]
```

### 3. Streamable HTTP Endpoints
**Concept**: Test completions via HTTP for integration
```bash
POST /complete
{
  "ref": {"type": "ref/prompt", "name": "review_code"},
  "argument": {"name": "language", "value": "py"}
}
```

## 🧠 Core Examples

### Prompt Completions
1. **Language**: `"py"` → `["python"]`
2. **Focus**: `"sec"` → `["security"]`  
3. **Framework** (with context): `"fast"` + `language="python"` → `["fastapi"]`

### Resource Completions
4. **GitHub Owner**: `"micro"` → `["microsoft"]`
5. **GitHub Repo** (with context): `"type"` + `owner="microsoft"` → `["typescript"]`

## 📚 Learning Path

### Step 1: Understand the Code
- Review `server.py` - Notice how completion data is organized
- See how `@mcp.completion()` decorator works
- Understand context-aware logic

### Step 2: Test with HTTP Client
- Start server: `uv run server.py`
- Run client: `uv run client.py` (in new terminal)
- Observe how context affects suggestions

### Step 3: Test with Postman
- Import the collection
- Test individual completion requests
- Experiment with different partial values

### Step 4: Extend and Experiment
- Add new languages or frameworks to the data
- Create new completion logic
- Test edge cases (empty values, no matches)

## 🔧 Key Implementation Details

### Completion Handler Structure
```python
@mcp.completion()
async def handle_completion(ref, argument, context):
    # Check if it's a prompt or resource
    if isinstance(ref, PromptReference):
        # Handle prompt argument completions
    elif isinstance(ref, ResourceTemplateReference):
        # Handle resource parameter completions
    return None  # No completions available
```

### Context Usage
```python
# Access context for context-aware completions
if context and context.arguments:
    other_param = context.arguments.get("param_name")
    # Use other_param to filter suggestions
```

### Response Format
```python
return Completion(
    values=["suggestion1", "suggestion2"],  # List of suggestions
    hasMore=False  # Whether more results are available
)
```

## 🌟 DACA Framework Integration

This completions server demonstrates DACA principles:

- **User Experience**: Intelligent auto-completion improves agent interaction
- **Standardization**: MCP completions work across different AI platforms  
- **Scalability**: HTTP endpoints enable integration with web applications
- **Simplicity**: Focused implementation for easy understanding and extension

## 📖 References

- [MCP Completions Specification](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/completion)
- Main README: `../README.md`
- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)

## 🎓 Next Steps

1. **Extend Completions**: Add more domains (databases, APIs, file types)
2. **Add Validation**: Handle edge cases and error conditions
3. **Performance**: Implement caching for large datasets
4. **Integration**: Use in real applications with Claude Desktop or other MCP clients
5. **Advanced Features**: Implement `hasMore` pagination for large result sets
