Resources and prompts

Matching a URI against a template

When a read arrives for docs://help/doc_shipping, the server must find which template it fits and pull out id = "doc_shipping". Think of a clerk checking an address against a form with one blank. For simple templates, where each {name} stands for one path segment, a regular expression does it:

import re

def match_template(template, uri):
    parts = re.split(r"(\{\w+\})", template)
    pattern = "".join(f"(?P<{p[1:-1]}>[^/]+)" if p.startswith("{") else re.escape(p) for p in parts)
    m = re.fullmatch(pattern, uri)
    return m.groupdict() if m else None

print(match_template("docs://help/{id}", "docs://help/doc_shipping"))
print(match_template("crm://customers/{cid}/orders/{oid}", "crm://customers/c42/orders/o7"))
print(match_template("docs://help/{id}", "docs://help/a/b"))

Each {name} becomes a named group that matches one or more characters other than /. Every other character is escaped, so dots and slashes in the template mean themselves. RFC 6570 defines richer forms too, such as {+path} that may include slashes, but this simple level covers most servers.

Prompts

A prompt is a form letter with blanks, written by someone who knows what works. prompts/list returns prompt definitions: name, title, description and arguments (each with a name, description and required flag). prompts/get with a name and arguments returns messages, ready to send to a model:

{"resultType": "complete", "description": "Review of Brand Awareness - Video",
 "messages": [{"role": "user", "content": {"type": "text", "text": "Here is one campaign's data: ... In three sentences, say how it's performing and suggest one change."}}]}

Messages can also embed resources or images. A missing required argument is error -32602. Hosts typically show prompts as slash commands: type /review_campaign cmp_103, and the host calls prompts/get and sends the messages.

from string import Template

PROMPT = Template("Write a $tone product description for $product, under $words words.")
ARGS = [{"name": "product", "required": True}, {"name": "tone", "required": False}, {"name": "words", "required": False}]
DEFAULTS = {"tone": "friendly", "words": "60"}

def get_prompt(arguments):
    missing = [a["name"] for a in ARGS if a["required"] and a["name"] not in arguments]
    if missing:
        raise ValueError(f"missing required arguments: {', '.join(missing)}")
    text = PROMPT.substitute({**DEFAULTS, **arguments})
    return {"resultType": "complete", "messages": [{"role": "user", "content": {"type": "text", "text": text}}]}

print(get_prompt({"product": "the River tent"})["messages"][0]["content"]["text"])
print(get_prompt({"product": "the {secret} mug", "tone": "playful"})["messages"][0]["content"]["text"])
try:
    get_prompt({})
except ValueError as err:
    print("rejected:", err)

import re

template = "docs://help/{id}"
pattern = "^" + re.escape(template).replace(r"\{id\}", "(?P<id>[^/]+)") + "$"
m = re.match(pattern, "docs://help/billing")
print(m.group("id"))

Who decides what

MCP has three primitives, and they differ mainly in who's in charge:

A common mistake is making everything a tool. If your data is something a person wants to attach, like a document, a resource fits better. The app can show a picker, and the model doesn't have to ask for it, or spend a turn finding it.

Prompts never run by themselves. A user chooses one, usually from a slash menu, and the host fills it in. They're templates, not automation.

In plain words: the model picks tools, the app or user picks resources, and the user picks prompts.

Don't list what you can't list

A server with 200,000 help articles shouldn't return all of them from resources/list. A client would have to fetch and hold them all, and most of them would never be used. A URI template, such as docs://help/{id}, describes the whole collection in one line. List only the handful of articles people use most, and let the template cover the rest.

Filling templates safely

str.format looks like the natural way to fill a prompt template. It isn't safe with user text. A form letter works because the blanks hold data. Trouble starts when what someone writes in a blank gets read as part of the form's instructions.

class Config:
    secret = "sk-123"

template = "Reply about: {topic}"
print(template.format(topic="my order"))

# A value is safe, but a template written with user text is not:
user_text = "{config.secret}"
print(("Reply about: " + user_text).format(config=Config))

If user text ever becomes part of the format string, the braces in it get read as instructions, and it can reach into the objects you pass in. Keep templates fixed, validate each argument, and use plain replacement for the values. Remember too that whatever the prompt contains is what the model will read, so a filled-in prompt is untrusted content. Treat it that way.

Reading a resource

A resource is read-only by design. Looking at a library book shouldn't change it. If reading something changes data, it should be a tool.