MCP Server

GoodMem exposes its retrieval tools through the Model Context Protocol (MCP) so LLM agents can search spaces, browse memories, look up models, and synthesize answers without writing custom HTTP integrations. The MCP server runs in-process inside the GoodMem REST server and reuses the same authentication, authorization, and audit pipeline as the rest of the API.

Endpoint

GoodMem MCP uses the Streamable HTTP transport. The endpoint is:

/mcp

For example, if your REST base URL is https://goodmem.example.com, MCP clients should connect to:

https://goodmem.example.com/mcp

The /mcp path sits at the REST root rather than under /v1. This hosted endpoint is HTTP-only; clients that can only speak stdio can wrap it with a shim such as mcp-remote. A separate npm package, @pairsystems/goodmem-mcp, provides a stdio MCP server with its own broader tool set — that is a different integration surface and is not covered by this page.

Connect a client

Most MCP clients accept a JSON config block listing the servers they should attach to. The exact field names vary by client, but the GoodMem-specific information is always the same:

• a URL pointing at <your-rest-base>/mcp
• an x-api-key header carrying a valid GoodMem API key

A representative config block:

{
  "mcpServers": {
    "goodmem": {
      "url": "https://goodmem.example.com/mcp",
      "headers": {
        "x-api-key": "gm_your_key"
      }
    }
  }
}

Consult your MCP client's own documentation for the exact location of its config file and the field names it expects. Once the client is connected, it discovers the GoodMem tools listed below via the standard MCP tools/list call.

Authentication

Authenticate with a GoodMem API key. The canonical header is:

x-api-key: <goodmem-api-key>

For MCP clients that only support bearer-token configuration, GoodMem also accepts:

Authorization: Bearer <goodmem-api-key>

Requests without a valid key receive 401 Unauthorized before any tool runs. Once authenticated, tools see exactly the spaces, memories, LLMs, and rerankers visible to that key — the underlying gRPC permission model is unchanged. Calls that pass authentication but lack permission for a specific resource follow the standard distinct-404/403 contract documented in Access Control.

Available tools

The early-access MCP surface exposes these tools:

Destructive and administrative operations are intentionally not exposed in the early-access surface.

Calling goodmem_retrieve

Most agents should start with goodmem_retrieve once they know which space to search. The tool is invoked through the standard MCP tools/call envelope; the GoodMem-specific portion is the arguments object:

{
  "query": "What product capabilities are described in the launch materials?",
  "space_ids": ["019dd100-49b8-7181-be3d-d62f6c96dd6a"],
  "retrieval_limit": 20,
  "result_limit": 10,
  "reranker": "none",
  "answer": false
}

When answer is false, GoodMem returns source chunks for the agent to analyze on its own. Set answer to true only when you want GoodMem to run server-side LLM synthesis from the retrieved source set; this triggers the ChatPostProcessor and consumes additional time and tokens.

reranker defaults to auto. With multiple visible rerankers and no clearly designated default, auto returns RERANKER_SELECTION_REQUIRED so the agent can pick one. Pass an explicit reranker UUID, or "none" to skip reranking entirely. The same auto-selection logic governs llm when answer=true, with one difference: llm has no "none" option, since answer synthesis always needs an LLM.

If you do not yet know a space UUID, call goodmem_list_spaces first.

Metadata filters

goodmem_retrieve and goodmem_list_memories accept GoodMem metadata filter expressions that operate on document-level JSON metadata. Common patterns:

CAST(val('$.department') AS text) = 'sales'
exists('$.tags[*]')
CAST(val('$.effectiveDate') AS DATE) >= CAST('2024-10-01' AS DATE)
CAST(val('$.title') AS text) ILIKE '%launch%'

String comparisons against val() results need an explicit CAST(... AS text). Without it, equality and ILIKE may silently return no matches or fail with an internal error.

The argument name is metadata_filter on goodmem_retrieve but plain filter on goodmem_list_memories. The expression syntax is identical; only the field name differs.

See Metadata Filters for the full filter syntax.

Capabilities and limits

• MCP runs on the REST server port, separate from the gRPC port used by the CLI.
• Requests are authenticated with GoodMem API keys and forwarded into the existing GoodMem service layer; audit logs and metrics are produced the same way as for REST and gRPC traffic.
• Tool responses include both human-readable text (for broad MCP-client compatibility) and structured content where the client supports it.
• Calls with answer=true, reranking enabled, or large output budgets can run long. Configure your MCP client with generous tool-call timeouts.
• goodmem_ping_inference reports provider failures inside its structured content (ok: false) rather than as MCP tool errors. Callers should inspect ok to distinguish a successful diagnostic call that found a broken provider from a tool that ran cleanly.

Troubleshooting

GoodMem's tools return repairable errors — structured payloads that name the failure and suggest a corrective next step — wherever the failure mode is well-understood. Each error includes a code, a human-readable message, and a next_action describing what to do. The most common codes:

Related links

• Access Control — how API keys, permissions, and visibility are evaluated.
• ChatPostProcessor — what answer=true actually runs.
• Metadata Filters — filter expression syntax used by goodmem_retrieve and goodmem_list_memories.
• Provider Proxy API — sibling surface for forwarding raw provider HTTP calls.