{"skill":{"slug":"alchemyst-mcp","displayName":"Alchemyst MCP Skill","summary":"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....","description":"---\nname: alchemyst-mcp\ndescription: >\n  Use this skill whenever you need to store, retrieve, search, or view persistent context\n  using the Alchemyst AI MCP server at mcp.getalchemystai.com/mcp/sse. Triggers include:\n  requests to \"remember\" or \"recall\" information across sessions, storing documents/notes/decisions\n  for later retrieval, searching project knowledge, or any task that involves reading from or\n  writing to Alchemyst's context store.\n---\n\n# Alchemyst AI MCP — Context Engine\n\n## Overview\n\nAlchemyst AI is a **persistent context layer** for AI applications. It stores documents,\nconversations, and structured knowledge externally so they can be retrieved on demand — across\nsessions, tools, and environments.\n\nThe MCP server is exposed as an SSE (Server-Sent Events) endpoint:\n\n```\nhttps://mcp.getalchemystai.com/mcp/sse\n```\n\nAuthentication is done via a **Bearer token** (your Alchemyst API key) passed as a request header.\n\n---\n\n## Prerequisites\n\n| Requirement | Detail |\n|---|---|\n| **Alchemyst API key** | Obtain from [platform.getalchemystai.com](https://platform.getalchemystai.com) |\n| **MCP-compatible client** | Claude Desktop, Cursor, VS Code + MCP extension, or custom agent |\n| **Transport** | SSE (`https://mcp.getalchemystai.com/mcp/sse`) |\n| **Auth header** | `Authorization: Bearer <YOUR_API_KEY>` |\n\n---\n\n## Claude Desktop Configuration\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"alchemyst\": {\n      \"url\": \"https://mcp.getalchemystai.com/mcp/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_ALCHEMYST_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n> **Never commit your API key.** Use an environment variable or secrets manager in production.\n\n---\n\n## Tools\n\nThe server exposes exactly four tools:\n\n---\n\n### `alchemyst_ai_search_context` — Semantic Search\n\nSearch the context store using a natural-language query. Returns documents ranked by semantic\nsimilarity.\n\n**When to use:** Before answering a question that might rely on stored knowledge; retrieving prior\ndecisions, docs, or instructions without manual lookup.\n\n#### Input Schema\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `query` | `string` | ✅ | Natural-language search query |\n| `similarity_threshold` | `number` (0–1) | ✅ | Maximum similarity threshold — results at or below this score are returned |\n| `minimum_similarity_threshold` | `number` (0–1) | ✅ | Floor — results below this score are excluded |\n| `scope` | `\"internal\"` \\| `\"external\"` | ❌ | Search scope; defaults to `\"internal\"` |\n| `metadata` | `object` \\| `null` | ❌ | Optional filter by file metadata; defaults to `null` |\n\n**Metadata filter fields** (all required if metadata object is provided):\n\n| Field | Type | Description |\n|---|---|---|\n| `fileName` | `string` | Name of file to filter by |\n| `fileSize` | `number` | File size in bytes |\n| `fileType` | `string` | MIME type |\n| `lastModified` | `string` | ISO 8601 datetime string |\n| `groupName` | `string[]` | Tag groups; defaults to `[\"default\"]` |\n\n> **Note:** Metadata field names use **camelCase** in the search tool (`fileName`, `fileSize`,\n> `fileType`, `lastModified`, `groupName`).\n\n#### Threshold Guidance\n\n- `similarity_threshold: 0.8` + `minimum_similarity_threshold: 0.5` → tight, precise results\n- `similarity_threshold: 0.7` + `minimum_similarity_threshold: 0.4` → broader, more permissive\n- Always set `minimum_similarity_threshold` lower than `similarity_threshold`\n\n#### Example Call\n\n```json\n{\n  \"query\": \"authentication token expiry policy\",\n  \"similarity_threshold\": 0.8,\n  \"minimum_similarity_threshold\": 0.5,\n  \"scope\": \"internal\",\n  \"metadata\": null\n}\n```\n\n---\n\n### `alchemyst_ai_add_context` — Store Context\n\nAdd one or more documents to the Alchemyst context store.\n\n**When to use:** Saving project requirements, architectural decisions, onboarding docs, meeting\nnotes, code conventions, or any knowledge you want to persist and retrieve later.\n\n#### Input Schema\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `user_id` | `string` | ✅ | Unique identifier of the user submitting context |\n| `organization_id` | `string` \\| `null` | ✅ | Organization ID; pass `null` if not applicable |\n| `documents` | `array` | ✅ | Array of document objects, each with a `content` string field (plus optional extra string fields) |\n| `source` | `string` | ✅ | Label describing where this context came from (e.g., `\"project.auth.decisions\"`) |\n| `context_type` | `\"resource\"` \\| `\"conversation\"` \\| `\"instruction\"` | ✅ | Type of context being stored |\n| `metadata` | `object` | ✅ | File metadata — all four fields required |\n| `scope` | `\"internal\"` \\| `\"external\"` | ❌ | Defaults to `\"internal\"` |\n\n**Metadata fields** (all required; note **snake_case** here, unlike the search tool):\n\n| Field | Type | Description |\n|---|---|---|\n| `file_name` | `string` | Name of the file or document |\n| `doc_type` | `string` | MIME type or document type (e.g., `\"text/markdown\"`) |\n| `modalities` | `string[]` | Modalities present (e.g., `[\"text\"]`, `[\"text\", \"image\"]`) |\n| `size` | `number` | Size in bytes |\n\n> ⚠️ **Key naming difference:** `add_context` uses **snake_case** metadata keys (`file_name`,\n> `doc_type`, `size`), while `search_context` uses **camelCase** (`fileName`, `fileType`,\n> `fileSize`). Match the case to the tool you're calling.\n\n#### Context Types\n\n| Value | Use for |\n|---|---|\n| `\"resource\"` | Files, documents, reference material, code |\n| `\"conversation\"` | Chat history, meeting transcripts, support threads |\n| `\"instruction\"` | Persistent rules, conventions, agent instructions |\n\n#### Source Naming Convention\n\nUse dot-separated hierarchical labels. This makes auditing straightforward:\n\n```\nproject.auth.decisions\nteam.onboarding.v2\nagent.instructions.sales\n```\n\n#### Example Call\n\n```json\n{\n  \"user_id\": \"user_abc123\",\n  \"organization_id\": \"org_xyz\",\n  \"documents\": [\n    { \"content\": \"All API routes use JWT auth with 15-minute token expiry.\" }\n  ],\n  \"source\": \"project.auth.decisions\",\n  \"context_type\": \"resource\",\n  \"scope\": \"internal\",\n  \"metadata\": {\n    \"file_name\": \"auth-decisions.md\",\n    \"doc_type\": \"text/markdown\",\n    \"modalities\": [\"text\"],\n    \"size\": 64\n  }\n}\n```\n\n---\n\n### `alchemyst_ai_context_mcp_view_context` — View Context Summary\n\nRetrieve a summary of all stored context for a given user and organization.\n\n**When to use:** Auditing what's in the context store, debugging missing context, or checking\nwhat knowledge is available before a session.\n\n#### Input Schema\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `user_id` | `string` | ✅ | User ID to get context for |\n| `organization_id` | `string` \\| `null` | ✅ | Organization ID; pass `null` if not applicable |\n\n#### Example Call\n\n```json\n{\n  \"user_id\": \"user_abc123\",\n  \"organization_id\": \"org_xyz\"\n}\n```\n\n---\n\n### `alchemyst_ai_context_mcp_view_docs` — View Stored Documents\n\nRetrieve the actual documents stored in the context store for a given user and organization.\n\n**When to use:** Listing stored documents, verifying content was saved correctly, or browsing\navailable knowledge before deciding what to add.\n\n#### Input Schema\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `user_id` | `string` | ✅ | User ID to get documents for |\n| `organization_id` | `string` \\| `null` | ✅ | Organization ID; pass `null` if not applicable |\n\n#### Example Call\n\n```json\n{\n  \"user_id\": \"user_abc123\",\n  \"organization_id\": \"org_xyz\"\n}\n```\n\n---\n\n## Workflow Patterns\n\n### Store → Search (basic memory pattern)\n\n1. Call `alchemyst_ai_add_context` to store a document\n2. Later, call `alchemyst_ai_search_context` with a relevant query to retrieve it\n3. Inject the retrieved content into your prompt as context\n\n### Audit before adding\n\n1. Call `alchemyst_ai_context_mcp_view_docs` to inspect what's already stored\n2. Only call `alchemyst_ai_add_context` if the knowledge isn't already present\n3. This avoids duplicating context and keeps the store clean\n\n### Pre-answer retrieval\n\nBefore answering any question that might depend on project-specific knowledge, call\n`alchemyst_ai_search_context` first. Prefer doing this proactively — don't wait for the user to\nexplicitly ask \"check the context store.\"\n\n---\n\n## Best Practices\n\n**Always populate metadata.** The `metadata` object is required on `add_context` — populate all\nfour fields every time. Missing metadata degrades retrieval quality significantly.\n\n**Chunk large documents.** Break large files into logical sections before adding. Each chunk\nshould be independently meaningful. Don't split mid-sentence or mid-concept.\n\n**Version your sources.** When content evolves, use versioned source labels\n(`project.arch.v1`, `project.arch.v2`) rather than re-adding to the same source. This preserves\nhistory.\n\n**Search before storing.** Run a search first to check whether similar content already exists\nbefore calling `add_context`. Avoid accumulating duplicates.\n\n**Mind the camelCase/snake_case split.** The metadata schema differs between tools — this is a\nquirk of the current API. Double-check field names when building payloads:\n- `add_context` → `file_name`, `doc_type`, `size` (snake_case)\n- `search_context` → `fileName`, `fileType`, `fileSize` (camelCase)\n\n**Pass `organization_id` explicitly.** Even when there's no org, pass `null` rather than\nomitting the field — it's required by the schema.\n\n---\n\n## Error Handling\n\n| Status | Meaning | Action |\n|---|---|---|\n| 400 | Bad request | Check required fields; verify `documents` is an array; check metadata schema |\n| 401 | Auth failure | Verify API key; confirm header is `Authorization: Bearer <key>` |\n| 403 | Permission denied | Check org/user scope permissions |\n| 404 | Not found | Confirm the `user_id` or `organization_id` is valid |\n| 422 | Unprocessable entity | Schema validation failed — check field types, required fields, and camelCase vs snake_case |\n| 429 | Rate limit | Back off exponentially; retry after delay |\n| 500+ | Server error | Retry twice with backoff; check [status.getalchemystai.com](https://status.getalchemystai.com) |\n\n---\n\n## Resources\n\n- Docs: [getalchemystai.com/docs](https://getalchemystai.com/docs)\n- MCP overview: [getalchemystai.com/docs/mcps/introduction](https://getalchemystai.com/docs/mcps/introduction)\n- Claude Desktop setup: [getalchemystai.com/docs/mcps/claude-desktop](https://getalchemystai.com/docs/mcps/claude-desktop)\n- API status: [status.getalchemystai.com](https://status.getalchemystai.com)\n- Python SDK: `pip install alchemystai`\n- Support: anuran@getalchemystai.com","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":232,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771349199133,"updatedAt":1778491567625},"latestVersion":{"version":"1.0.0","createdAt":1771349199133,"changelog":"Alchemyst MCP Skill 1.0.0 — Initial Release\n\n- Provides seamless storage, retrieval, and semantic search of persistent context using the Alchemyst AI MCP server.\n- Supports four core actions: semantic search, context storage, context summary view, and document retrieval.\n- Allows filtering and detailed document metadata for precise context management.\n- Integrates with multiple clients (Claude Desktop, Cursor, VS Code, custom agents).\n- Detailed configuration and usage examples included for quick setup.","license":null},"metadata":null,"owner":{"handle":"anuran-roy","userId":"s1708pkcnxfg47z6b7jxty2wg5884drb","displayName":"Anuran Roy","image":"https://avatars.githubusercontent.com/u/76481787?v=4"},"moderation":null}