mcp: add developer endpoint instructions for ontology-guided queries

[bobbyiliev]

As discussed here

[github-actions]

Thanks for opening this PR! Here are a few tips to help make the review process smooth for everyone.

PR title guidelines

• Use imperative mood: "Fix X" not "Fixed X" or "Fixes X"
• Be specific: "Fix panic in catalog sync when controller restarts" not "Fix bug" or "Update catalog code"
• Prefix with area if helpful: compute: , storage: , adapter: , sql:

Pre-merge checklist

• The PR title is descriptive and will make sense in the git log.
• This PR has adequate test coverage / QA involvement has been duly considered. (trigger-ci for additional test/nightly runs)
• If this PR includes major user-facing behavior changes, I have pinged the relevant PM to schedule a changelog post.
• This PR has an associated up-to-date design doc, is a design doc (template), or is sufficiently small to not require a design.
• If this PR evolves an existing $T ⇔ Proto$T mapping (possibly in a backwards-incompatible way), then it is tagged with a T-proto label.
• If this PR will require changes to cloud orchestration or tests, there is a companion cloud PR to account for those changes that is tagged with the release-blocker label (example).

[mtabebe]

This is great! A few questions/comments

1. I don't think we can actually merge now, because these tables don't exist. And if they do they will likely not have the mz_ name for now (as we aren't sure if we are going to use built in tables for now).
2. If I have more detailed prompts, what is the best way to load that as context (https://github.com/MaterializeInc/materialize/pull/36051/changes#diff-a96642aa1a069c9e0c155c6169b5398b9d4a3c55205918c6ce17318b76439c96) That is is there a way to give the MCP server the MD files?

In the meantime, I'm going to cherry pick this change locally for testing!

Thanks for the fast turn around!!

[bobbyiliev]

Thanks @mtabebe good catches!

• On the ontology tables, you're right, I'll hold off on merging the instructions PR until the ontology lands and we have final table names. Easy to update once the schema is settled!
• On loading detailed prompts, the MCP instructions field (in the initialize response) is good for short guardrails but it's a single string, not great for full runbooks. The longer diagnostic content lives in the agent-skills SKILL.md which Claude Code loads into context when the skill is installed. There's no MCP protocol mechanism to serve arbitrary files to the client today. One option down the road would be MCP resources (part of the spec but we haven't implemented it) which could serve markdown docs to the client on request.

[mtabebe]

ah cool about the skill, in my hack here, I just included the file directly 🤣 5d7c5d0#diff-21bbf589585fdbbf4f4d53d77a3beb188699f8ca61c689658de2db260dd753ed

[mtabebe]

LGTM, I think this is a good starting point and will be easy to iterate on.

In my commit I was a bit stronger with the language, since I was getting frustrated with Claude hallucination: 5d7c5d0#diff-21bbf589585fdbbf4f4d53d77a3beb188699f8ca61c689658de2db260dd753ed

But given we aren't going to merge right away, I'm happy to approve

[bobbyiliev]

Thanks @mtabebe! Sounds good to me! I'll wait for your signal before merging this 🙌

[mtabebe]

@bobbyiliev minor comment, it seems likely the tables will be of the form: mz_internal.mz_ontology_link_types once they go into the built ins.

So: mz_internal.mz_ontology_link_types, mz_internal.mz_ontology_properties, mz_internal.mz_ontology_semantic_types, mz_internal.mz_ontology_entity_types