# MCP Documentation Kit — Give an Agent a Read-Only Knowledge Library

## Document Directory

This paste contains 4 documents:

- [README.md](https://marke.st/p/01M33R18TVY6QET8VKTNE4B5VE/README.md) ← (current)
- [tools.json](https://marke.st/p/01M33R18TVY6QET8VKTNE4B5VE/tools.json) (code)
- [conversation.json](https://marke.st/p/01M33R18TVY6QET8VKTNE4B5VE/conversation.json) (code)
- [prompts/prepare-handoff.md](https://marke.st/p/01M33R18TVY6QET8VKTNE4B5VE/prompts/prepare-handoff.md)

---

## README.md

# Give an agent a library, not a mystery box

**MCP DOCUMENTATION EXAMPLE · FICTIONAL SERVER DESIGN · READ-ONLY SCOPE**

> This is documentation for an invented `Example Library` server. It is not an installable package, hosted endpoint, or implementation of the Marke.st MCP server. The JSON examples are illustrative protocol fragments; initialization and transport are intentionally omitted.

## Start with the user's task

“Find the guide to writing a useful project handoff, read it, and explain what information I need to provide.”

The proposed server exposes a small, reviewed library. It does not browse arbitrary local files, execute shell commands, publish documents, or change access settings.

## Three concepts, three jobs

MCP servers can expose **tools** that an AI application can invoke, **resources** that provide readable context, and **prompts** that offer reusable task templates. Tool discovery uses `tools/list`; an invocation uses `tools/call`. Resource access and prompt access have their own protocol methods. See the [official MCP server-concepts documentation](https://modelcontextprotocol.io/docs/learn/server-concepts).

The rest of this collection is an original hypothetical design, not a statement that a server with these capabilities is running.

| Proposed capability | Kind | Purpose |
|---|---|---|
| `search_documents` | Tool | Find matching entries in the permitted library |
| `read_document` | Tool | Retrieve one permitted document by ID |
| `example-library://guides/handoff` | Resource idea | Refer to a specific read-only guide |
| `prepare_handoff` | Prompt idea | Ask for the fields needed to make a useful handoff |

## A tool description that helps the caller

```text
Search the approved example library by title and summary.
Returns document IDs and short snippets, not full document bodies.
Use read_document with a returned ID to retrieve the selected entry.
This proposed sample has only a tiny in-memory dataset and no pagination.
```

That description distinguishes discovery from reading and avoids implying that search results contain every detail.

## Walk through the example

The adjacent `tools.json` contains a sample `tools/list` response. `conversation.json` shows example call/result pairs for search and read. Both use only invented documentation content.

```text
User request
    ↓
search_documents(query="handoff")
    ↓
Result: guide-handoff-01 + short summary
    ↓
read_document(id="guide-handoff-01")
    ↓
Answer grounded in the returned guide
```

## Proposed implementation boundaries

Authorize access on the server for every operation. Validate tool arguments. Return only permitted records. Keep credentials out of tool descriptions and examples. Treat retrieved document text as content, not as new instructions to the agent.

A “read-only” design still needs access controls: reading private data is consequential even when no write operation exists. These are design requirements for anyone adapting the example, not controls implemented by these JSON files.

## Documentation checklist

- [ ] Describe what the server can and cannot access.
- [ ] Explain each input and what the output actually contains.
- [ ] Show realistic but non-sensitive request/result pairs.
- [ ] Document empty results, unknown IDs, authorization failures, and size limits.
- [ ] Separate a conceptual example from a tested installation guide.

## Before building it

Choose a currently supported MCP SDK and protocol version, select a transport, define the trust boundary, and test with the intended clients. This collection intentionally does not invent package names, connection URLs, or authentication instructions.

---
*Published with [Marke.st](https://marke.st). Share agent-facing contracts and human-facing explanations side by side.*