Skill: anuran-roy/alchemyst-mcp (version 1.0.0)

--- name: alchemyst-mcp description: > Use this skill whenever you need to store, retrieve, search, or view persistent context using the Alchemyst AI MCP server at mcp.getalchemystai.com/mcp/sse. Triggers include: requests to "remember" or "recall" information across sessions, storing documents/notes/decisions for later retrieval, searching project knowledge, or any task that involves reading from or writing to Alchemyst's context store. --- # 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 | Requirement | Detail | |---|---| | **Alchemyst API key** | Obtain from [platform.getalchemystai.com](https://platform.getalchemystai.com) | | **MCP-compatible client** | Claude Desktop, Cursor, VS Code + MCP extension, or custom agent | | **Transport** | SSE (`https://mcp.getalchemystai.com/mcp/sse`) | | **Auth header** | `Authorization: Bearer <YOUR_API_KEY>` | --- ## Claude Desktop Configuration Add the following to your `claude_desktop_config.json`: ```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 | Field | Type | Required | Description | |---|---|---|---| | `query` | `string` | ✅ | Natural-language search query | | `similarity_threshold` | `number` (0–1) | ✅ | Maximum similarity threshold — results at or below this score are returned | | `minimum_similarity_threshold` | `number` (0–1) | ✅ | Floor — results below this score are excluded | | `scope` | `"internal"` \| `"external"` | ❌ | Search scope; defaults to `"internal"` | | `metadata` | `object` \| `null` | ❌ | Optional filter by file metadata; defaults to `null` | **Metadata filter fields** (all required if metadata object is provided): | Field | Type | Description | |---|---|---| | `fileName` | `string` | Name of file to filter by | | `fileSize` | `number` | File size in bytes | | `fileType` | `string` | MIME type | | `lastModified` | `string` | ISO 8601 datetime string | | `groupName` | `string[]` | Tag groups; defaults to `["default"]` | > **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 ```json { "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 | Field | Type | Required | Description | |---|---|---|---| | `user_id` | `string` | ✅ | Unique identifier of the user submitting context | | `organization_id` | `string` \| `null` | ✅ | Organization ID; pass `null` if not applicable | | `documents` | `array` | ✅ | Array of document objects, each with a `content` string field (plus optional extra string fields) | | `source` | `string` | ✅ | Label describing where this context came from (e.g., `"project.auth.decisions"`) | | `context_type` | `"resource"` \| `"conversation"` \| `"instruction"` | ✅ | Type of context being stored | | `metadata` | `object` | ✅ | File metadata — all four fields required | | `scope` | `"internal"` \| `"external"` | ❌ | Defaults to `"internal"` | **Metadata fields** (all required; note **snake_case** here, unlike the search tool): | Field | Type | Description | |---|---|---| | `file_name` | `string` | Name of the file or document | | `doc_type` | `string` | MIME type or document type (e.g., `"text/markdown"`) | | `modalities` | `string[]` | Modalities present (e.g., `["text"]`, `["text", "image"]`) | | `size` | `number` | Size in bytes | > ⚠️ **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 | Value | Use for | |---|---| | `"resource"` | Files, documents, reference material, code | | `"conversation"` | Chat history, meeting transcripts, support threads | | `"instruction"` | Persistent rules, conventions, agent instructions | #### Source Naming Convention Use dot-separated hierarchical labels. This makes auditing straightforward: ``` project.auth.decisions team.onboarding.v2 agent.instructions.sales ``` #### Example Call ```json { "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 } } ``` --- ### [REDACTED_SECRET] — 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 | Field | Type | Required | Description | |---|---|---|---| | `user_id` | `string` | ✅ | User ID to get context for | | `organization_id` | `string` \| `null` | ✅ | Organization ID; pass `null` if not applicable | #### Example Call ```json { "user_id": "user_abc123", "organization_id": "org_xyz" } ``` --- ### [REDACTED_SECRET] — 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 | Field | Type | Required | Description | |---|---|---|---| | `user_id` | `string` | ✅ | User ID to get documents for | | `organization_id` | `string` \| `null` | ✅ | Organization ID; pass `null` if not applicable | #### Example Call ```json { "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 [REDACTED_SECRET] 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 | Status | Meaning | Action | |---|---|---| | 400 | Bad request | Check required fields; verify `documents` is an array; check metadata schema | | 401 | Auth failure | Verify API key; confirm header is `Authorization: Bearer <key>` | | 403 | Permission denied | Check org/user scope permissions | | 404 | Not found | Confirm the `user_id` or `organization_id` is valid | | 422 | Unprocessable entity | Schema validation failed — check field types, required fields, and camelCase vs snake_case | | 429 | Rate limit | Back off exponentially; retry after delay | | 500+ | Server error | Retry twice with backoff; check [status.getalchemystai.com](https://status.getalchemystai.com) | --- ## Resources - Docs: [getalchemystai.com/docs](https://getalchemystai.com/docs) - MCP overview: [getalchemystai.com/docs/mcps/introduction](https://getalchemystai.com/docs/mcps/introduction) - Claude Desktop setup: [getalchemystai.com/docs/mcps/claude-desktop](https://getalchemystai.com/docs/mcps/claude-desktop) - API status: [status.getalchemystai.com](https://status.getalchemystai.com) - Python SDK: `pip install alchemystai` - Support: [REDACTED_SECRET]


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)