# Mcp Beyond Tools

> A reference MCP server demonstrating correct use of all three primitives: tools, resources, and prompts. Companion to the AAIF blog "The Unknowns of MCP

- **Type:** MCP server
- **Install:** `agentstack add mcp-shriramkv-mcp-beyond-tools`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shriramkv](https://agentstack.voostack.com/s/shriramkv)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shriramkv](https://github.com/shriramkv)
- **Source:** https://github.com/shriramkv/mcp-beyond-tools

## Install

```sh
agentstack add mcp-shriramkv-mcp-beyond-tools
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-beyond-tools

**A reference MCP server that uses all three primitives correctly: tools, resources, and prompts.**

Most MCP servers in the wild expose everything as a tool, even plain data reads. That forces the host through a code-execution consent flow for what should have been a simple read, bloats the model's context window with tool schemas, and makes auditing harder. This repository is a small, complete, tested server (**DocVault**, a local document vault) built to demonstrate the correct split.

## The rule of thumb this repo demonstrates

| Primitive | Use it for | DocVault examples |
|---|---|---|
| **Resource** | Read-only context, no side effects | `docvault://docs` (catalogue), `docvault://docs/{name}` (document content) |
| **Tool** | Actions: side effects or real computation | `search_vault`, `add_note` |
| **Prompt** | Reusable, parameterised workflows the server authors | `summarise_document`, `compare_documents` |

Note what is deliberately absent: there is no `read_document` tool and no `list_documents` tool. Reads are resources. Keeping the tool list down to genuine actions is what keeps your context window lean when a host connects many servers at once.

## Quickstart

Requires Python 3.10+.

```bash
git clone https://github.com/shriramkv/mcp-beyond-tools.git
cd mcp-beyond-tools
pip install -r requirements.txt

# Run the end-to-end demo client (no AI host needed)
python examples/client_demo.py
```

The demo client connects over stdio, lists all three primitives, reads a resource, calls a tool, and fetches a prompt. Expected final line:

```
All three primitives exercised successfully.
```

## Using it from Claude Desktop

Add this to your `claude_desktop_config.json` (adjust the path):

```json
{
  "mcpServers": {
    "docvault": {
      "command": "python",
      "args": ["-m", "docvault.server"],
      "cwd": "/absolute/path/to/mcp-beyond-tools"
    }
  }
}
```

Restart Claude Desktop. You will see two tools, the document resources, and two prompts. Try: *"Search the vault for 'stateless' and then read the matching document."* Watch how the search goes through a tool call while the read arrives as a resource.

## Repository structure

```
mcp-beyond-tools/
├── docvault/
│   ├── server.py          # the server: 2 resources, 2 tools, 2 prompts
│   └── sample_docs/       # seed documents served as resources
├── examples/
│   └── client_demo.py     # stdio client exercising every primitive
├── requirements.txt
└── LICENSE                # MIT
```

## Why this matters (the short version)

1. **Security and consent.** Tools represent code execution and deserve a consent flow. Reads do not. Modelling reads as resources means the consent ceremony is reserved for things that can actually change state.
2. **Context economics.** Every tool schema you expose is context the model pays for on every turn. Two tools instead of five is a real saving once a host connects twenty servers.
3. **Auditability.** When the tool list contains only actions, the audit log of tool calls becomes a log of things that happened, not a log of things that were merely looked at.

## Author

Shriram K Vasudevan ([@shriramkv](https://github.com/shriramkv))
YouTube: https://www.youtube.com/shriramvasudevan

Licensed under MIT.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shriramkv](https://github.com/shriramkv)
- **Source:** [shriramkv/mcp-beyond-tools](https://github.com/shriramkv/mcp-beyond-tools)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-shriramkv-mcp-beyond-tools
- Seller: https://agentstack.voostack.com/s/shriramkv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.