The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external data sources and tools. It defines three primitives - tools, resources, and prompts - that give LLMs structured access to systems they would otherwise have no visibility into. The dedicated MCP documentation workflow that captures server capabilities, transport configuration, authentication, and all three primitive types in a structured, publishable format stored in your Git repository alongside REST APIs, schemas, and architecture documentation.
The Three MCP Primitives
MCP organises server capabilities into three complementary primitive types, each serving a distinct role in how AI assistants interact with external systems.
Tools
Actions the AI can perform: API calls, database queries, file operations, calculations. Each tool declares input/output schemas, annotations (read-only, destructive, idempotent), error scenarios, and examples. Tools are model-controlled - the LLM decides when to call them.
Resources
Data the AI can read: files, database records, API responses, live system state. Resources use URIs (concrete or templated) and support subscriptions for real-time updates. Application-controlled - the host decides what resources to expose.
Prompts
Reusable prompt templates with typed arguments and expected message flows. Prompts standardise how the AI interacts with specific domains, so that the AI maintains consistent tone, format, and information extraction across conversations.
Tool Documentation
Tools are the most common MCP primitive. NeoArc captures everything an LLM and a developer need to understand a tool's behaviour, safety characteristics, and integration requirements.
Tool Annotation Safety Matrix
NeoArc renders tool annotations as a semantic safety badge, helping both developers and LLMs understand the risk profile of each tool at a glance.
| readOnly | destructive | idempotent | Classification | Colour |
|---|
| true | - | - | Read-only query | Green |
| false | false | true | Safe idempotent write | Blue |
| false | false | false | Non-idempotent write | Amber |
| false | true | true | Destructive (idempotent) | Orange |
| false | true | false | Destructive action | Red |
Resource Documentation
Resources expose data to AI assistants without requiring tool calls. They support both concrete URIs for fixed data and URI templates for parameterised access.
URI Templates
Parameterised URIs like ecommerce://catalogue/{category} with documented parameters, examples, and descriptions. The viewer highlights template parameters with accent colouring.
Subscriptions
Resources can be marked as subscribable, enabling real-time notifications when the underlying data changes. Document the subscription behaviour so consumers know what to expect.
Audience Control
Specify whether a resource is intended for the user, the assistant, or both. This metadata helps the host application decide what to surface and when.
Prompt Documentation
Prompts are reusable templates that standardise how AI assistants interact with specific domains. They define arguments, expected message flows, and concrete examples.
Typed Arguments
Named parameters with descriptions, required flags, and completion support. The server can provide auto-complete suggestions for argument values at runtime.
Expected Messages
Define the conversation flow: which messages are user-provided, which are assistant-generated, and what content type each uses (text, image, resource reference).
Worked Examples
Complete input/output examples showing argument values mapped to the expected conversation. Serves as both documentation and quality assurance for prompt engineering.
Server Configuration
MCP servers require transport, authentication, and capability documentation that goes beyond the primitives themselves.
Transport Configuration
Document stdio (command, args, env vars, working directory) and streamable HTTP (URL, session management, SSE support) transports. Both can be configured per server.
OAuth 2.1 Authentication
Full OAuth 2.1 configuration: authorisation and token URLs, scopes with descriptions, PKCE requirement, and dynamic client registration support.
Capability Declarations
Document what each server supports: tool list changes, resource subscriptions, prompt updates, logging levels, and completion providers. Clients use this to adapt their behaviour.
LLM Instructions
Free-form guidance for the AI assistant: behavioural rules, data access policies, preferred interaction patterns, and safety constraints.
Sampling Configuration
When the server needs to call the LLM itself (reverse direction), document the use cases, model preferences, context inclusion rules, and token budgets.
Version Controlled
MCP definitions are JSON files stored in your Git repository. Track changes in pull requests, review tool annotations, and roll back when needed.
Import and Export
NeoArc supports importing and exporting MCP server definitions in standard formats for interoperability with the broader MCP ecosystem.
MCP Manifest Import
Import a standard MCP manifest JSON file to auto-generate tool, resource, and prompt definitions. Inline JSON schemas are automatically extracted into separate schema files.
MCP Manifest Export
Export the server definition as a standard MCP manifest JSON with tools, resources, and prompts. Schema references are resolved inline for portability.
Claude Desktop Config
Export a Claude Desktop configuration snippet for stdio-based servers with command, arguments, and environment variables ready to paste into claude_desktop_config.json.
Example: E-Commerce AI Assistant
A complete MCP server definition for an e-commerce platform demonstrating all three primitives, transport configuration, and OAuth authentication.
Tools
Three tools demonstrating different annotation profiles: a read-only search, a read-only status query, and a non-idempotent write operation.
Resources
A templated resource for browsing the product catalogue and a static resource for the return policy.
Prompts
Two prompt templates: one for generating customer service responses with tone adaptation, and one for personalised product recommendations.
Viewer Experience
The published site includes an MCP server browser that presents all three primitives in a navigable hierarchy with dedicated detail viewers for each entity type.
Navigation Panel
Browse servers with tools, resources, and prompts grouped by primitive type. Each category shows a count badge and supports collapse/expand. Active item highlighting and keyboard navigation.
Annotation Badges
Tool detail views display colour-coded safety badges derived from the annotation matrix. At a glance, developers and LLMs can identify read-only queries versus destructive operations.
Searchable
MCP definitions are included in the published site search index. Find tools by name, resources by URI, and prompts by argument names or descriptions.
Interactive Examples
Tool examples display input arguments and expected output with syntax highlighting. Prompt examples show the full message flow with role badges and copy-paste-ready content.
Server Info Viewer
Dedicated viewer for server configuration: transport details, capability matrix, OAuth scopes, sampling configuration, and LLM instructions in a distinctive callout.
Mobile Support
The MCP server browser is fully responsive with a mobile drawer that maintains the three-primitive hierarchy and collapsible server groups.
Use Cases
AI Agent Integration Docs
Document the MCP contract for your AI-powered services so consuming teams know exactly what tools are available, what data they can access, and what safety constraints apply.
Developer Reference
Provide developers building MCP clients with tool schemas, error scenarios, and concrete examples so they integrate with the server correctly from the start.
AI Safety Governance
Track tool annotations, destructive operation declarations, and LLM instruction guidelines across your MCP servers. Keep AI safety policies documented and version-controlled.
Related Documentation
API Documentation
Document REST APIs with full endpoint specifications, OpenAPI import and export, seven HTTP methods, parameters, request and response bodies linked to shared schemas, authentication schemes, and a published API browser. REST is part of the API documentation suite (REST, GraphQL, gRPC, AsyncAPI, Webhooks, MCP) sharing a unified schema layer.
Webhook API Documentation
Document webhook-based integrations with event definitions, HMAC signature verification, delivery guarantees, retry policies, dead letter queues, circuit breakers, and consumer guidance. The structured webhook editor captures what architects need to express about push-based event notifications.
Async Event API Documentation
Document event-driven and asynchronous APIs with channels, operations, messages, protocol bindings across a wide range of protocols, security schemes, reusable traits, and AsyncAPI 3.0 export in NeoArc Studio.
gRPC API Documentation
Document gRPC APIs with services, methods, all four streaming types, proto message definitions, standard gRPC status codes, Google RPC error detail types, interceptor chains, retry and hedging policies, HTTP transcoding, proto import and export, and a published gRPC API browser with streaming flow diagrams.
Schema Editor
Define data structures with field types covering strings, numbers, booleans, objects, arrays and more, type specialisations for fine-grained modelling, and validation rules covering type safety, cardinality, referential integrity and cross-field constraints. Create reusable schemas that stay synchronised across your documentation.
