# MCP Protocol vs REST API in MCP Memory Service: When to Use Each Interface

> Understand the MCP protocol vs REST API in MCP Memory Service. Learn when to use each interface for Claude Desktop or generic HTTP clients benefiting from shared auth and differing transport styles.

- Repository: [Henry/mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)
- Tags: deep-dive
- Published: 2026-02-28

---

**The MCP Memory Service exposes both a JSON-RPC 2.0 MCP endpoint for Claude Desktop integrations and standard REST endpoints for generic HTTP clients, with both sharing the same authentication layer but differing in transport style, discovery mechanisms, and client ecosystem compatibility.**

The doobidoo/mcp-memory-service provides dual interfaces to accommodate different integration patterns. While the **MCP (Model Context Protocol)** offers tool-driven RPC interactions optimized for Claude Code and Claude Desktop, the **REST API** provides resource-oriented endpoints compatible with any HTTP client. Understanding the architectural differences between these protocols ensures you select the right interface for your specific use case.

## Transport and Protocol Architecture

### MCP Protocol Interface

The MCP implementation utilizes **JSON-RPC 2.0** messages transmitted over HTTP POST to the `/mcp` endpoint. Each payload contains a `method` field (e.g., `initialize`, `tools/list`, `tools/call`) and optional `params`. This design allows Claude Desktop to discover available tools dynamically and execute them through a single multiplexed endpoint.

The router definition and tool dispatch logic reside in **[`src/mcp_memory_service/web/api/mcp.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)**. This file defines the `MCP_TOOLS` list and the `handle_tool_call` function that routes incoming JSON-RPC requests to the appropriate memory operations.

### REST API Interface

The REST implementation follows standard HTTP semantics using verbs like `GET`, `POST`, `PUT`, and `DELETE` on resource-oriented URLs such as `/api/memories` and `/api/search`. This approach leverages FastAPI's automatic OpenAPI documentation generation and integrates seamlessly with generic HTTP clients, browsers, and third-party automation platforms.

The endpoint definitions are located in **[`src/mcp_memory_service/web/api/memories.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/memories.py)** for CRUD operations and **[`src/mcp_memory_service/web/api/search.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/search.py)** for semantic search functionality.

## Authentication and Security

Both interfaces share identical authentication mechanisms enforced through FastAPI dependencies. The application applies **`require_read_access`** and **`require_write_access`** dependencies globally, ensuring that whether you connect via MCP or REST, the same bearer-token or API-key validation occurs.

This unified security layer is configured in **[`src/mcp_memory_service/web/app.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)**, where both routers are attached to the main FastAPI application instance after OAuth authentication routers are established.

## When to Use the MCP Protocol

Choose the MCP interface when building integrations specifically for **Claude Desktop** or **Claude Code**. The protocol excels in scenarios requiring:

- **Tool Discovery**: Clients can query `tools/list` to receive JSON schemas for all available operations, enabling dynamic UI generation and type-safe client code.
- **Single Endpoint Architecture**: All operations route through `/mcp`, simplifying client configuration when multiple memory operations (store, retrieve, list, delete) must be multiplexed.
- **RPC-Style Interactions**: When your client expects to call remote procedures rather than manipulate resources via HTTP semantics.

## When to Use the REST API

Select the REST interface for **generic HTTP clients** and external service integrations. This approach is optimal when:

- **Standard HTTP Semantics**: You require conventional `GET`, `POST`, `PUT`, `DELETE` verbs with explicit HTTP status codes and caching capabilities.
- **Resource-Oriented URLs**: You prefer endpoints like `/api/memories/{id}` that map directly to domain entities rather than RPC method names.
- **Third-Party Integrations**: Connecting with automation platforms like Zapier, IFTTT, or custom dashboards that expect standard REST conventions and OpenAPI documentation.

## Implementation Examples

### Storing Memories via REST

Use the `/api/memories` endpoint with a standard HTTP POST request:

```bash
curl -X POST http://localhost:8000/api/memories \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "content": "Important onboarding checklist",
        "tags": ["onboarding", "checklist"],
        "memory_type": "note",
        "metadata": {"project": "MCP"}
      }'

```

*Implementation reference:* The `store_memory` endpoint is defined in **[`src/mcp_memory_service/web/api/memories.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/memories.py)**.

### Storing Memories via MCP

Send a JSON-RPC 2.0 envelope to the `/mcp` endpoint:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "store_memory",
    "arguments": {
      "content": "Important onboarding checklist",
      "tags": ["onboarding","checklist"],
      "memory_type": "note",
      "metadata": {"project":"MCP"}
    }
  }
}

```

Transmit this payload via HTTP POST to `http://localhost:8000/mcp`. The server returns a JSON-RPC response containing the stored memory's hash in the `result` field.

*Implementation reference:* The MCP router processes `tools/call` in **[`src/mcp_memory_service/web/api/mcp.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)** and dispatches to `handle_tool_call`.

### Searching Memories via REST

Perform semantic search using query parameters:

```bash
curl -G http://localhost:8000/api/search \
  -H "Authorization: Bearer $MCP_API_KEY" \
  --data-urlencode "query=onboarding" \
  --data-urlencode "limit=5"

```

*Implementation reference:* The search endpoint is implemented in **[`src/mcp_memory_service/web/api/search.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/search.py)**.

### Searching Memories via MCP

Invoke the retrieval tool via JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "retrieve_memory",
    "arguments": {
      "query": "onboarding",
      "limit": 5
    }
  }
}

```

Send this to the `/mcp` endpoint. The response contains the memory list in `result.content[0].text`.

*Implementation reference:* `retrieve_memory` is defined in the `MCP_TOOLS` list within **[`src/mcp_memory_service/web/api/mcp.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)**.

## Summary

- **MCP Protocol**: Use JSON-RPC 2.0 via `/mcp` for Claude Desktop/Code integrations requiring tool discovery, single-endpoint multiplexing, and RPC-style interactions. Implementation resides in **[`src/mcp_memory_service/web/api/mcp.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)**.

- **REST API**: Use standard HTTP verbs on `/api/memories` and `/api/search` for generic clients, third-party integrations, and resource-oriented architectures. Implemented in **[`src/mcp_memory_service/web/api/memories.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/memories.py)** and **[`src/mcp_memory_service/web/api/search.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/search.py)**.

- **Authentication**: Both interfaces share identical security layers through FastAPI dependencies (`require_read_access`, `require_write_access`) configured in **[`src/mcp_memory_service/web/app.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)**.

- **Selection Criteria**: Choose MCP for Claude ecosystem tooling; choose REST for universal HTTP compatibility and standard REST conventions.

## Frequently Asked Questions

### What is the main transport difference between MCP and REST in this service?

The **MCP protocol** uses **JSON-RPC 2.0** messages sent over HTTP POST to a single `/mcp` endpoint, where the `method` field determines the operation (e.g., `tools/call`). The **REST API** uses standard HTTP verbs (`GET`, `POST`, `PUT`, `DELETE`) mapped to specific resource URLs like `/api/memories` and `/api/search`, following conventional HTTP semantics and status codes.

### Can I use the same authentication token for both MCP and REST endpoints?

Yes. Both interfaces utilize the identical **FastAPI dependency injection** system. The `require_read_access` and `require_write_access` dependencies enforce authentication globally, whether you send a JSON-RPC payload to `/mcp` or a standard HTTP request to `/api/memories`. Configure your bearer token or API key once and use it for both protocols.

### Which interface should I choose for integrating with Claude Desktop?

Use the **MCP protocol**. Claude Desktop and Claude Code expect the **Model Context Protocol** interface to discover available tools via `tools/list` and execute them via `tools/call`. This JSON-RPC approach allows the Claude client to dynamically understand the memory service capabilities without hardcoded endpoint knowledge, providing seamless tool integration through the `/mcp` endpoint defined in **[`src/mcp_memory_service/web/api/mcp.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)**.

### Is there a performance difference between MCP and REST calls?

Both interfaces run on the same **FastAPI** application and share the underlying business logic, so core performance characteristics are identical. However, the **MCP protocol** incurs slight overhead for JSON-RPC envelope parsing and method dispatch in `handle_tool_call` within **[`src/mcp_memory_service/web/api/mcp.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)**, while **REST** benefits from FastAPI's native path operation optimization and standard HTTP caching mechanisms where applicable. For high-throughput scenarios, REST may offer marginally lower latency due to reduced parsing overhead.