API Reference¶
Complete API reference for MCP integration in Rea.
Protocol Messages¶
MCP uses JSON-RPC 2.0 for all communication.
Request Format¶
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search",
"arguments": {"query": "test"}
}
}
Response Format¶
Error Format¶
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Invalid Request",
"data": {}
}
}
Lifecycle Methods¶
initialize¶
Establishes connection and negotiates capabilities.
Request:
{
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {
"roots": {"listChanged": true}
},
"clientInfo": {
"name": "rea-mcp-client",
"version": "1.0.0"
}
}
}
Response:
{
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {"listChanged": true},
"resources": {"subscribe": true},
"prompts": {}
},
"serverInfo": {
"name": "notion-mcp-server",
"version": "1.0.0"
}
}
}
notifications/initialized¶
Sent by client after successful initialization.
Tool Methods¶
tools/list¶
List available tools.
Request:
Response:
{
"result": {
"tools": [
{
"name": "search",
"description": "Search for pages",
"inputSchema": {
"type": "object",
"properties": {
"query": {"type": "string"}
},
"required": ["query"]
}
}
]
}
}
tools/call¶
Execute a tool.
Request:
{
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "meeting notes"
}
}
}
Response:
{
"result": {
"content": [
{
"type": "text",
"text": "{\"results\": [...]}"
}
],
"isError": false
}
}
Content Types:
| Type | Fields | Description |
|---|---|---|
text |
text |
Plain text content |
image |
data, mimeType |
Base64-encoded image |
resource |
resource |
Embedded resource |
Resource Methods¶
resources/list¶
List available resources.
Request:
Response:
{
"result": {
"resources": [
{
"uri": "notion://workspace/info",
"name": "Workspace Info",
"mimeType": "application/json"
}
]
}
}
resources/read¶
Read a resource.
Request:
Response:
{
"result": {
"contents": [
{
"uri": "notion://workspace/info",
"mimeType": "application/json",
"text": "{\"name\": \"My Workspace\"}"
}
]
}
}
resources/subscribe¶
Subscribe to resource changes.
Request:
Prompt Methods¶
prompts/list¶
List available prompts.
Request:
Response:
{
"result": {
"prompts": [
{
"name": "code_review",
"description": "Review code for issues",
"arguments": [
{
"name": "code",
"description": "Code to review",
"required": true
}
]
}
]
}
}
prompts/get¶
Get a prompt with arguments.
Request:
{
"method": "prompts/get",
"params": {
"name": "code_review",
"arguments": {
"code": "function add(a, b) { return a + b; }"
}
}
}
Response:
{
"result": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Please review this code..."
}
}
]
}
}
Notifications¶
notifications/tools/list_changed¶
Server notifies client when tools change.
notifications/resources/list_changed¶
Server notifies client when resources change.
notifications/resources/updated¶
Server notifies client when a subscribed resource updates.
Rea REST API¶
Connections¶
List Connections¶
Response:
{
"connections": [
{
"id": 1,
"name": "notion",
"server_type": "notion",
"enabled": true,
"last_connected_at": "2024-01-15T10:30:00Z"
}
]
}
Create Connection¶
Body:
Test Connection¶
Response:
{
"success": true,
"tools_count": 12,
"server_info": {
"name": "notion-mcp-server",
"version": "1.0.0"
}
}
Delete Connection¶
Tools¶
List Tools¶
Response:
{
"tools": [
{
"fullName": "notion.search",
"name": "search",
"description": "Search for pages and databases",
"connection": "notion",
"inputSchema": {...}
}
]
}
Call Tool¶
Body:
Response:
Chat¶
Send Message¶
Body:
Response:
{
"message": "I found 3 meeting notes in your Notion workspace...",
"tools_used": ["notion.search"]
}
Error Codes¶
JSON-RPC Errors¶
| Code | Message | Description |
|---|---|---|
| -32700 | Parse error | Invalid JSON |
| -32600 | Invalid Request | Not a valid request object |
| -32601 | Method not found | Unknown method |
| -32602 | Invalid params | Invalid method parameters |
| -32603 | Internal error | Internal server error |
MCP Errors¶
| Code | Message | Description |
|---|---|---|
| -32001 | Connection failed | Failed to connect to server |
| -32002 | Timeout | Request timed out |
| -32003 | Tool not found | Unknown tool name |
| -32004 | Resource not found | Unknown resource URI |
| -32005 | Unauthorized | Missing or invalid credentials |
HTTP Status Codes¶
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Rate Limited |
| 500 | Server Error |
PHP SDK Classes¶
MCPClientInterface¶
interface MCPClientInterface
{
public function connect(): void;
public function isConnected(): bool;
public function getServerInfo(): array;
public function getCapabilities(): array;
public function listTools(): array;
public function callTool(string $name, array $arguments = []): array;
public function listResources(): array;
public function readResource(string $uri): array;
public function listPrompts(): array;
public function getPrompt(string $name, array $arguments = []): array;
public function disconnect(): void;
}
MCPManagerService¶
class MCPManagerService
{
public function getClient(User $user, string $connectionName): MCPClientInterface;
public function getAllTools(User $user): array;
public function callTool(User $user, string $fullName, array $arguments): array;
public function disconnectUser(User $user): void;
public function disconnectAll(): void;
}
Tool Attributes¶
#[McpTool(
name: 'tool_name',
description: 'Tool description'
)]
public function toolMethod(string $arg1, ?int $arg2 = null): array;
Resource Attributes¶
#[McpResource(
uri: 'resource://path',
name: 'Resource Name',
mimeType: 'application/json',
isTemplate: false
)]
public function resourceMethod(): array;
Prompt Attributes¶
#[McpPrompt(
name: 'prompt_name',
description: 'Prompt description'
)]
public function promptMethod(string $arg): array;