Alchemyst AI MCP — Context Engine

Overview

Alchemyst AI is a persistent context layer for AI applications. It stores documents, conversations, and structured knowledge externally so they can be retrieved on demand — across sessions, tools, and environments.

The MCP server is exposed as an SSE (Server-Sent Events) endpoint:

https://mcp.getalchemystai.com/mcp/sse

Authentication is done via a Bearer token (your Alchemyst API key) passed as a request header.

Prerequisites

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "alchemyst": {
      "url": "https://mcp.getalchemystai.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ALCHEMYST_API_KEY"
      }
    }
  }
}

Never commit your API key. Use an environment variable or secrets manager in production.

Tools

The server exposes exactly four tools:

alchemyst_ai_search_context — Semantic Search

Search the context store using a natural-language query. Returns documents ranked by semantic similarity.

When to use: Before answering a question that might rely on stored knowledge; retrieving prior decisions, docs, or instructions without manual lookup.

Input Schema

Metadata filter fields (all required if metadata object is provided):

Note: Metadata field names use camelCase in the search tool (fileName, fileSize, fileType, lastModified, groupName).

Threshold Guidance

• similarity_threshold: 0.8 + minimum_similarity_threshold: 0.5 → tight, precise results
• similarity_threshold: 0.7 + minimum_similarity_threshold: 0.4 → broader, more permissive
• Always set minimum_similarity_threshold lower than similarity_threshold

Example Call

{
  "query": "authentication token expiry policy",
  "similarity_threshold": 0.8,
  "minimum_similarity_threshold": 0.5,
  "scope": "internal",
  "metadata": null
}

alchemyst_ai_add_context — Store Context

Add one or more documents to the Alchemyst context store.

When to use: Saving project requirements, architectural decisions, onboarding docs, meeting notes, code conventions, or any knowledge you want to persist and retrieve later.

Input Schema

Metadata fields (all required; note snake_case here, unlike the search tool):

⚠️ Key naming difference: add_context uses snake_case metadata keys (file_name, doc_type, size), while search_context uses camelCase (fileName, fileType, fileSize). Match the case to the tool you're calling.

Context Types

Source Naming Convention

Use dot-separated hierarchical labels. This makes auditing straightforward:

project.auth.decisions
team.onboarding.v2
agent.instructions.sales

Example Call

{
  "user_id": "user_abc123",
  "organization_id": "org_xyz",
  "documents": [
    { "content": "All API routes use JWT auth with 15-minute token expiry." }
  ],
  "source": "project.auth.decisions",
  "context_type": "resource",
  "scope": "internal",
  "metadata": {
    "file_name": "auth-decisions.md",
    "doc_type": "text/markdown",
    "modalities": ["text"],
    "size": 64
  }
}

alchemyst_ai_context_mcp_view_context — View Context Summary

Retrieve a summary of all stored context for a given user and organization.

When to use: Auditing what's in the context store, debugging missing context, or checking what knowledge is available before a session.

Input Schema

Example Call

{
  "user_id": "user_abc123",
  "organization_id": "org_xyz"
}

alchemyst_ai_context_mcp_view_docs — View Stored Documents

Retrieve the actual documents stored in the context store for a given user and organization.

When to use: Listing stored documents, verifying content was saved correctly, or browsing available knowledge before deciding what to add.

Input Schema

Example Call

{
  "user_id": "user_abc123",
  "organization_id": "org_xyz"
}

Workflow Patterns

Store → Search (basic memory pattern)

1. Call alchemyst_ai_add_context to store a document
2. Later, call alchemyst_ai_search_context with a relevant query to retrieve it
3. Inject the retrieved content into your prompt as context

Audit before adding

1. Call alchemyst_ai_context_mcp_view_docs to inspect what's already stored
2. Only call alchemyst_ai_add_context if the knowledge isn't already present
3. This avoids duplicating context and keeps the store clean

Pre-answer retrieval

Before answering any question that might depend on project-specific knowledge, call alchemyst_ai_search_context first. Prefer doing this proactively — don't wait for the user to explicitly ask "check the context store."

Best Practices

Always populate metadata. The metadata object is required on add_context — populate all four fields every time. Missing metadata degrades retrieval quality significantly.

Chunk large documents. Break large files into logical sections before adding. Each chunk should be independently meaningful. Don't split mid-sentence or mid-concept.

Version your sources. When content evolves, use versioned source labels (project.arch.v1, project.arch.v2) rather than re-adding to the same source. This preserves history.

Search before storing. Run a search first to check whether similar content already exists before calling add_context. Avoid accumulating duplicates.

Mind the camelCase/snake_case split. The metadata schema differs between tools — this is a quirk of the current API. Double-check field names when building payloads:

• add_context → file_name, doc_type, size (snake_case)
• search_context → fileName, fileType, fileSize (camelCase)

Pass organization_id explicitly. Even when there's no org, pass null rather than omitting the field — it's required by the schema.

Error Handling

Resources

• Docs: getalchemystai.com/docs
• MCP overview: getalchemystai.com/docs/mcps/introduction
• Claude Desktop setup: getalchemystai.com/docs/mcps/claude-desktop
• API status: status.getalchemystai.com
• Python SDK: pip install alchemystai
• Support: anuran@getalchemystai.com