MCP_USAGE.md•7.81 kB
# Model Context Protocol (MCP) Usage Guide
This document provides detailed information on how to use the Model Context Protocol (MCP) integration with the Unsplash API.
## Table of Contents
- [Introduction to MCP](#introduction-to-mcp)
- [MCP Server Configuration](#mcp-server-configuration)
- [Available MCP Tools](#available-mcp-tools)
- [Using MCP with AI Models](#using-mcp-with-ai-models)
- [Claude](#claude)
- [Other MCP-Compatible Models](#other-mcp-compatible-models)
- [Advanced Usage](#advanced-usage)
- [Troubleshooting](#troubleshooting)
## Introduction to MCP
The Model Context Protocol (MCP) is an open standard that enables AI models to interact with external tools and services in a structured way. It provides a standardized interface for AI models to:
- Discover available tools and their capabilities
- Call tools with specific parameters
- Receive structured responses from tools
This implementation uses [FastAPI-MCP](https://github.com/tadata-org/fastapi-mcp), which automatically converts FastAPI endpoints into MCP tools.
## MCP Server Configuration
The MCP server is configured in the `src/app/api.py` file:
```python
from fastapi_mcp import FastApiMCP
app = FastAPI(description="Unsplash API")
# Create FastAPI-MCP instance
mcp = FastApiMCP(app)
# Mount the MCP server
mcp.mount(mount_path="/mcp", transport="sse")
```
The MCP server is available at `/mcp` and uses Server-Sent Events (SSE) as the transport mechanism.
## Available MCP Tools
The MCP server exposes the following tools:
### 1. Search Tool
**Name:** `search_photos`
**Description:** Search for images on Unsplash based on a query. Returns metadata including description, author, links, and likes.
**Parameters:**
- `query` (string): Search term (Default: "nature")
- `page` (integer): Page number (Default: 1)
- `per_page` (integer): Number of photos per page (Default: 10)
- `order_by` (string): Photo ordering (Default: "relevant", Options: "relevant", "latest")
**Example Call:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "mcp/call_tool",
"params": {
"name": "search_photos",
"arguments": {
"query": "mountains",
"page": 1,
"per_page": 5,
"order_by": "latest"
}
}
}
```
### 2. Photos Tool
**Name:** `get_photos`
**Description:** Retrieve a collection of photos from Unsplash. Returns metadata including description, author, links, and likes.
**Parameters:**
- `page` (integer): Page number (Default: 1)
- `per_page` (integer): Number of photos per page (Default: 10)
- `order_by` (string): Photo ordering (Default: "latest", Options: "latest", "oldest", "popular")
**Example Call:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "mcp/call_tool",
"params": {
"name": "get_photos",
"arguments": {
"page": 1,
"per_page": 5,
"order_by": "popular"
}
}
}
```
### 3. Random Tool
**Name:** `get_random_photos`
**Description:** Get random photos from Unsplash based on an optional query. Returns metadata including description, author, links, and likes.
**Parameters:**
- `query` (string): Search term to filter random photos (Default: "nature")
- `count` (integer): Number of photos to return (Default: 1, Maximum: 30)
**Example Call:**
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "mcp/call_tool",
"params": {
"name": "get_random_photos",
"arguments": {
"query": "ocean",
"count": 3
}
}
}
```
## Using MCP with AI Models
### Claude
To use the Unsplash API MCP with Claude:
1. Start the Unsplash API server:
```bash
python main.py
```
2. In Claude Desktop:
- Go to Settings > Tools
- Click "Add Tool"
- Enter the MCP server URL: `http://localhost:8000/mcp`
- Name the tool (e.g., "Unsplash API")
- Click "Add"
3. In your conversation with Claude, you can now ask it to:
- Search for images on Unsplash
- Get popular photos
- Find random images on specific topics
Example prompts:
- "Find me some mountain landscape photos on Unsplash"
- "Show me the most popular photos on Unsplash right now"
- "Get 3 random ocean photos from Unsplash"
### Other MCP-Compatible Models
For other MCP-compatible models, refer to their specific documentation on how to connect external MCP servers. The connection URL will be:
```
http://your-server:8000/mcp
```
## Advanced Usage
### Custom MCP Client
You can create a custom MCP client to interact with the server programmatically:
```python
import requests
import json
class UnsplashMCPClient:
def __init__(self, base_url="http://localhost:8000/mcp"):
self.base_url = base_url
self.jsonrpc_url = f"{base_url}/jsonrpc"
self.request_id = 0
def _make_request(self, method, params=None):
self.request_id += 1
payload = {
"jsonrpc": "2.0",
"id": self.request_id,
"method": method
}
if params:
payload["params"] = params
response = requests.post(self.jsonrpc_url, json=payload)
return response.json()
def list_tools(self):
return self._make_request("mcp/list_tools")
def search_photos(self, query="nature", page=1, per_page=10, order_by="relevant"):
return self._make_request("mcp/call_tool", {
"name": "search_photos",
"arguments": {
"query": query,
"page": page,
"per_page": per_page,
"order_by": order_by
}
})
def get_photos(self, page=1, per_page=10, order_by="latest"):
return self._make_request("mcp/call_tool", {
"name": "get_photos",
"arguments": {
"page": page,
"per_page": per_page,
"order_by": order_by
}
})
def get_random_photos(self, query="nature", count=1):
return self._make_request("mcp/call_tool", {
"name": "get_random_photos",
"arguments": {
"query": query,
"count": count
}
})
# Usage example
if __name__ == "__main__":
client = UnsplashMCPClient()
# List available tools
tools = client.list_tools()
print(json.dumps(tools, indent=2))
# Search for mountain photos
mountain_photos = client.search_photos("mountains", per_page=3)
print(json.dumps(mountain_photos, indent=2))
```
## Troubleshooting
### Common Issues
1. **Connection Refused**
If you get a "Connection Refused" error, make sure:
- The Unsplash API server is running
- You're using the correct port (default: 8000)
- There are no firewall issues blocking the connection
2. **Authentication Errors**
If you get authentication errors from Unsplash:
- Check that your `UNSPLASH_CLIENT_ID` is correctly set in the `.env` file
- Verify that your Unsplash API key is valid and has not exceeded rate limits
3. **MCP Protocol Errors**
If you get MCP protocol errors:
- Check that you're using the correct JSON-RPC format
- Verify that the tool name and parameters are correct
- Make sure you're using the correct MCP endpoint (`/mcp/jsonrpc`)
### Debugging
To enable debug logging for the MCP server, modify the `src/app/api.py` file:
```python
import logging
# Configure logger for MCP requests with DEBUG level
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("mcp_logger")
```
This will provide more detailed logs about MCP requests and responses.
### Getting Help
If you encounter issues not covered in this guide:
1. Check the [FastAPI-MCP documentation](https://github.com/tadata-org/fastapi-mcp)
2. Open an issue on the project's GitHub repository
3. Consult the [MCP specification](https://modelcontextprotocol.io) for protocol details