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

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. 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 for CRUD operations and 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, 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:

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.

Storing Memories via MCP

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

{
  "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 and dispatches to handle_tool_call.

Searching Memories via REST

Perform semantic search using query parameters:

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.

Searching Memories via MCP

Invoke the retrieval tool via JSON-RPC:

{
  "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.

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.

• 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 and 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.

• 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}