Skip to main content
Glama
Dosk3n

Glyph Hold MCP

by Dosk3n
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Glyph Hold MCP

Local stdio MCP server for connecting Codex and other MCP clients to Glyph Hold.

This repo is intentionally separate from Glyph Hold. It does not access the SQLite database directly. It talks to a running Glyph Hold instance through the public /api/v1 HTTP API.

Requirements

  • Python 3.12+

  • A running Glyph Hold instance

  • A Glyph Hold API key created from the dashboard

Example URL:

GLYPHHOLD_URL=https://glyphhold.example.com

Related MCP server: MCP HTTP Client Server

Local Setup

Choose a place on your machine where you keep local tool repos. Clone this repo there:

cd ~/coding_projects
git clone git@github.com:Dosk3n/glyphhold-mcp.git
cd glyphhold-mcp

Create the local Python environment:

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

Create the local environment file:

cp .env.example .env

Edit .env:

nano .env

Set:

GLYPHHOLD_URL=https://your-glyphhold-host.example.com
GLYPHHOLD_API_KEY=gh_live_xxxxxxxxxxxxxxxxx

Create GLYPHHOLD_API_KEY from the Glyph Hold dashboard.

Useful scopes:

  • memories:read

  • memories:write

  • secrets:write

  • secrets:reveal

Only grant secrets:reveal if you want the MCP client to be able to reveal secret values after an explicit user request.

Codex CLI Config

Find the full path to the cloned repo:

pwd

If pwd prints:

/home/you/coding_projects/glyphhold-mcp

then add this to ~/.codex/config.toml:

[mcp_servers.glyphhold]
command = "/home/you/coding_projects/glyphhold-mcp/.venv/bin/python"
args = ["-m", "glyphhold_mcp.server"]
cwd = "/home/you/coding_projects/glyphhold-mcp"

Use your real path from pwd. The important parts are:

command = <repo path>/.venv/bin/python
cwd     = <repo path>

You do not need to put the API key in Codex config. The MCP server loads GLYPHHOLD_URL and GLYPHHOLD_API_KEY from the .env file in the cloned repo.

Start Codex from any project as normal.

Inside Codex, run:

/mcp

You should see the glyphhold MCP server connected.

TLS Certificate Errors

If a tool returns an error like:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

Python does not trust the certificate chain for your Glyph Hold URL.

Best fix: point the MCP server at the CA bundle that signs your internal certificate:

GLYPHHOLD_CA_BUNDLE=/path/to/ca-bundle.pem

For a trusted private test deployment, you can disable verification in .env:

GLYPHHOLD_VERIFY_SSL=false

Do not use GLYPHHOLD_VERIFY_SSL=false for an internet-facing deployment.

Updating

To update the local MCP server later:

cd ~/coding_projects/glyphhold-mcp
git pull
. .venv/bin/activate
pip install -e ".[dev]"

Tools

Health and categories:

  • glyphhold_health

  • list_categories

Memory tools:

  • list_memories

  • get_memory

  • search_memories

  • prefetch_memories

  • find_similar_memories

  • prepare_memory_write

  • create_memory

  • update_memory

  • update_memory_confidence

  • archive_memory

  • supersede_memory

  • list_memory_revisions

  • restore_memory_revision

  • delete_memory

Secret tools:

  • search_secrets

  • get_secret_metadata

  • create_secret

  • update_secret

  • delete_secret

  • reveal_secret

  • reveal_secret_env

Secret values are only returned by reveal_secret and reveal_secret_env. Permanent deletes require an exact confirmation value.

Stable Error Responses

Successful tool responses keep their native Glyph Hold payloads. Recoverable HTTP, transport, timeout, configuration, and response errors are returned as normal MCP results so one failed request cannot invalidate the client's MCP connection:

{
  "ok": false,
  "error": {
    "type": "not_found",
    "message": "Glyph Hold request failed: HTTP 404: Secret not found",
    "retryable": false,
    "status": 404
  }
}

Errors are logged to stderr using the tool name, error type, status, and retry classification. Authorization headers, API keys, and secret values are never included in MCP error payloads or diagnostic logs.

Available Tools

7 tools
create_memoryB

Create a Glyph Hold memory after confirming it should be stored durably.

confidence must be 1-5. auto_prefetch_level must be one of never, low, normal, high, or pinned.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
tagsNo
titleYes
summaryNo
confidenceNoConfidence score from 1 to 5.
category_idYes
auto_prefetch_levelNonormal

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits. It only mentions parameter constraints (already in schema) and that the memory is stored durably. It omits side effects, required permissions, reversibility, or any nuance beyond creation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, no wasted words. However, given the tool's complexity (7 parameters), it may be overly minimal, but it remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description fails to provide context on invocation order, prerequisites (beyond 'confirming'), or when to use this tool. For a creation tool with 7 parameters and no annotation help, it is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14%. The description repeats enum values for confidence and auto_prefetch_level that are already defined in the schema, adding no new meaning. No explanation is given for the other five parameters (body, tags, title, summary, category_id).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a 'Glyph Hold memory' with the verb 'create', unambiguously identifying the resource and action. It does not conflict with sibling tools like create_secret (different resource) or search_memories (different action).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'after confirming it should be stored durably' implies a prerequisite but does not provide explicit guidance on when to use this tool versus alternatives like create_secret or search_memories. No when-not or exclusion criteria are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_secretC

Create encrypted Glyph Hold secret metadata and value.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostNo
nameYes
tagsNo
scopeNo
valueYes
serviceNo
value_typeNotext
descriptionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It lacks details on permissions, rate limits, idempotency, or side effects. The phrase 'encrypted' hints at security but is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, one sentence long, and starts with the action. However, it sacrifices necessary detail for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (8) and zero schema description coverage, the description is severely incomplete. An agent cannot infer parameter purposes or proper invocation without additional context. The presence of an output schema does not compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no parameter descriptions). The description does not explain any of the 8 parameters, including required 'name' and 'value', or the optional ones like 'value_type' and 'tags'. It adds no semantic value beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Create') and the resource ('encrypted Glyph Hold secret metadata and value'). It distinguishes from sibling tools like 'reveal_secret' by specifying creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'create_memory' or 'reveal_secret'. There is no mention of prerequisites, exclusions, or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

glyphhold_healthA

Check the configured Glyph Hold service health and version.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description does not disclose behavioral traits like authentication, side effects, or rate limits. Only states what it checks.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no unnecessary words, perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple with 0 parameters and an output schema, so the brief description is mostly complete. Could mention it is a health check/ping, but fine.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. Description adds no param info, but baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool checks service health and version, distinguishing it from sibling tools that deal with memories and secrets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. While siblings are different, the description does not provide when/when-not context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_categoriesA

List available Glyph Hold memory categories.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations available; description only states behavior implied by name, without disclosing safety, auth, or side effects. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, perfectly concise and front-loaded. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple list tool with no params, but lacks context on what categories are, how many, or when they change.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100% trivially. Description adds no param info, but baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'list' and resource 'Glyph Hold memory categories', exactly matching the tool name. No ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like search_memories or create_memory. Context is not provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

prefetch_memoriesB

Ask Glyph Hold for conservative memory context relevant to a message.

ParametersJSON Schema
NameRequiredDescriptionDefault
agentNocodex
messageYes
max_charsNoMaximum character budget.
max_tokensNoMaximum token estimate.
max_memoriesNoMaximum memories to prefetch.
summaries_onlyNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states 'conservative' but does not clarify behavior like whether it mutates state, requires special permissions, or how it selects memories. With no annotations provided, the description only partially discloses the tool's traits; it is adequate but lacks important details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence. It is concise but lacks structure and does not earn its place by providing sufficient detail. More context could be added without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 6 parameters, no annotations, and an output schema (which reduces need for return description), the description is still too sparse. It does not explain the purpose of each parameter or the output format, leaving gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 50% of parameters with descriptions (max_chars, max_tokens, max_memories). The description adds no additional meaning beyond the schema. Missing schema descriptions for 'agent', 'message', and 'summaries_only' are not compensated by the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific action 'Ask' and identifies the resource as 'conservative memory context relevant to a message.' It distinguishes from sibling 'search_memories' by implying a focused, limited retrieval. However, the verb 'Ask' is slightly unusual and the exact nature of the output is vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidelines on when to use this tool versus siblings like 'search_memories'. The phrase 'conservative memory context' hints at a specific use case, but there is no direct guidance on when to prefer this tool or when to avoid it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reveal_secretC

Reveal a secret value only when the user explicitly asks for the value.

ParametersJSON Schema
NameRequiredDescriptionDefault
purposeNoMCP reveal requested by Codex
id_or_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavioral traits. It mentions the 'only when user explicitly asks' constraint but lacks details on security, permissions, side effects, or error handling for a reveal operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is concise but omits critical information, making it insufficient rather than efficiently complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, zero parameter descriptions, and no explanation of return values despite having an output schema, the description is far from complete for an agent to use this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, requiring the description to explain parameters. Description does not mention id_or_name or purpose at all, leaving their meaning and usage entirely unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb (reveal), resource (secret value), and condition (only when user explicitly asks). It effectively distinguishes from siblings like create_secret.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage context (user explicitly asks) but provides no explicit when-to-use or when-not-to-use guidance compared to sibling tools like list_categories or search_memories.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_memoriesB

Search Glyph Hold memories with deterministic SQLite FTS.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of memories.
queryYes
categoryNo
include_archivedNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It only mentions 'deterministic SQLite FTS' but omits any behavioral traits like side effects, rate limits, or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise. However, it is slightly underspecified, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description does not need to explain return values. However, it is incomplete about query syntax and filtering behavior, which are important for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no information about parameters beyond the schema, which has only 25% description coverage. The 'limit' parameter has a schema description, but 'query', 'category', and 'include_archived' lack explanations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search'), the resource ('Glyph Hold memories'), and the method ('deterministic SQLite FTS'), distinguishing it from siblings like create_memory or prefetch_memories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like prefetch_memories, nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.1.0
    • First observedcreate_memory
    • First observedcreate_secret
    • First observedglyphhold_health
    • First observedlist_categories
    • First observedprefetch_memories
    • First observedreveal_secret
    • First observedsearch_memories
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct concept: memory vs secret, different retrieval methods (prefetch vs search), health check, categories. No overlap confuses selection.

Naming Consistency5/5

All tools follow snake_case verb_noun pattern (create_memory, create_secret, list_categories, etc.) with consistent naming conventions.

Tool Count5/5

7 tools cover the core functionalities of memory and secret management without bloat, appropriate for the server's purpose.

Completeness3/5

Missing update/delete operations for both memories and secrets, and no explicit list or get tool for single memories or secrets. Gaps may impede full lifecycle management.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers