> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leanmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Prompts and Resources Efficiently

> Best practices for leveraging prompts and resources in MCP servers

MCP has three primitives: **Tools**, **Resources**, and **Prompts**. While Tools get all the attention, Resources and Prompts serve distinct purposes that are often misunderstood.

***

## The Three Primitives

```mermaid theme={null}
flowchart LR
    subgraph Agent-Driven
        T[Tools]
    end
    subgraph User-Driven
        R[Resources]
        P[Prompts]
    end
    
    T --> LLM[LLM Provider<br/>Anthropic / OpenAI]
    R --> UI[Client UI<br/>Cursor / Windsurf]
    P --> UI
```

| Primitive     | Control       | Purpose                    | Client Support     |
| ------------- | ------------- | -------------------------- | ------------------ |
| **Tools**     | Agent-driven  | Actions with side effects  | ✅ Widely supported |
| **Resources** | User-driven   | Read-only data attachments | ⚠️ Limited support |
| **Prompts**   | User or Agent | Instructions/templates     | ⚠️ Limited support |

<Warning>
  **Resources and Prompts require client-side support.** Not all MCP clients implement them. Tools are universally supported because they're handled by LLM providers (Anthropic, OpenAI).
</Warning>

***

## Resources: User-Controlled Data

### What Are Resources?

Resources are **read-only data** that users can attach to their input. Key points:

* **User decides** — not the agent
* **Agent cannot access resources directly** — it must use Tools
* **Tools control access** — authentication, scopes, permissions

```mermaid theme={null}
flowchart TD
    U[User] -->|Attaches| R[Resource]
    R -->|Added to| I[Input Context]
    I --> A[Agent/LLM]
    A -->|Wants more data?| T[Tool]
    T -->|Checks auth & scopes| D[Database]
```

### Real-World Examples

The best example is the **@ command** in Cursor, Windsurf, and Android Studio:

| Client             | @ Command       | What It Attaches    |
| ------------------ | --------------- | ------------------- |
| **Cursor**         | `@file.ts`      | File contents       |
| **Windsurf**       | `@PR #123`      | Pull request diff   |
| **Android Studio** | `@build.gradle` | Build configuration |

When you type `@file.ts`, you're adding a **resource** to your prompt. The user explicitly chooses what context to include.

### When to Use Resources

```typescript theme={null}
import { Resource } from 'leanmcp';

@Resource({ description: "Current user's profile" })
async userProfile() {
  return {
    name: "John Doe",
    role: "Developer",
    preferences: { theme: "dark", language: "en" }
  };
}

@Resource({ description: "Project configuration" })
async projectConfig() {
  return {
    name: "my-app",
    version: "1.0.0",
    dependencies: { ... }
  };
}
```

**Use resources for:**

* Configuration files
* User profiles
* Project metadata
* Any read-only context users might want to attach

<Note>
  Resources are **not** for data the agent should fetch on its own. That's what Tools are for.
</Note>

***

## Prompts: Instructions for Agents

### What Are Prompts?

Prompts are **instructions** that tell the agent how to behave. They can be:

* **User-added** — Explicitly attached by the user
* **Agent-picked** — Agent selects relevant prompts when needed

```mermaid theme={null}
flowchart TD
    subgraph User-Added
        U[User] -->|Selects| P1[Prompt Template]
    end
    subgraph Agent-Picked
        A[Agent] -->|Chooses relevant| P2[Prompt Template]
    end
    P1 --> C[Combined Instructions]
    P2 --> C
    C --> L[LLM Behavior]
```

### Real-World Examples

The best example is **Guidelines** in Cursor and Windsurf:

| Client       | Feature          | Purpose                            |
| ------------ | ---------------- | ---------------------------------- |
| **Cursor**   | `.cursorrules`   | Project-specific coding guidelines |
| **Windsurf** | `.windsurfrules` | Project-specific behavior          |
| **Both**     | Guidelines panel | Agent instructions                 |

These are **prompts** — instructions that shape how the agent generates code.

### When to Use Prompts

```typescript theme={null}
import { Prompt } from 'leanmcp';

@Prompt({ description: "Code review guidelines" })
codeReviewPrompt() {
  return {
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `You are a senior code reviewer. Follow these rules:
1. Check for security vulnerabilities
2. Ensure proper error handling
3. Verify edge cases are covered
4. Suggest performance improvements
5. Keep feedback constructive`
      }
    }]
  };
}

@Prompt({ description: "API documentation writer" })
apiDocPrompt() {
  return {
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Generate API documentation with:
- Clear endpoint descriptions
- Request/response examples
- Error codes and meanings
- Authentication requirements`
      }
    }]
  };
}
```

**Use prompts for:**

* Coding standards
* Review guidelines
* Documentation templates
* Any reusable instructions

***

## Tools vs Resources vs Prompts

```mermaid theme={null}
flowchart TD
    subgraph Tools
        T1[Agent decides when to call]
        T2[Can have side effects]
        T3[Controlled by LLM provider]
        T4[Auth & scopes enforced]
    end
    
    subgraph Resources
        R1[User decides when to attach]
        R2[Read-only data]
        R3[Controlled by client UI]
        R4[No auth needed - user explicit]
    end
    
    subgraph Prompts
        P1[User or agent selects]
        P2[Instructions only]
        P3[Controlled by client UI]
        P4[Shapes agent behavior]
    end
```

| Question               | Answer                                                                  |
| ---------------------- | ----------------------------------------------------------------------- |
| Who decides to use it? | **Tools**: Agent / **Resources**: User / **Prompts**: Both              |
| Can it modify data?    | **Tools**: Yes / **Resources**: No / **Prompts**: No                    |
| Needs client support?  | **Tools**: No (LLM handles) / **Resources**: Yes / **Prompts**: Yes     |
| Purpose?               | **Tools**: Actions / **Resources**: Context / **Prompts**: Instructions |

***

## Client Support Reality

<Warning>
  **The hard truth:** Most MCP clients only support Tools.
</Warning>

| Client             | Tools | Resources   | Prompts   |
| ------------------ | ----- | ----------- | --------- |
| **Claude Desktop** | ✅     | ✅           | ✅         |
| **Cursor**         | ✅     | ✅ (@ files) | ✅ (rules) |
| **Windsurf**       | ✅     | ✅ (@ files) | ✅ (rules) |
| **ChatGPT**        | ✅     | ❌           | ❌         |
| **Custom clients** | ✅     | Varies      | Varies    |

If your MCP needs broad client support, **focus on Tools**. Use Resources and Prompts as progressive enhancements for clients that support them.

***

## Best Practices

### For Resources

1. **Keep them read-only** — Resources should never modify state
2. **Make them user-relevant** — Only expose what users would want to attach
3. **Provide fallbacks** — If resources aren't supported, expose similar data via Tools

```typescript theme={null}
// Resource for clients that support it
@Resource({ description: "Project config" })
async projectConfig() {
  return await this.getConfig();
}

// Tool fallback for clients that don't
@Tool({ description: "Get project config" })
async getProjectConfig() {
  return await this.getConfig();
}
```

### For Prompts

1. **Keep them focused** — One prompt per behavior/task
2. **Make them reusable** — Generic enough for multiple contexts
3. **Don't duplicate** — If it's in the prompt, don't repeat in tool descriptions

```typescript theme={null}
// ❌ BAD: Overly specific
@Prompt({ description: "Review React TypeScript code on Monday" })

// ✅ GOOD: Reusable
@Prompt({ description: "Code review guidelines" })
```

***

## Summary

| Primitive     | Control | Best For                   | Client Support |
| ------------- | ------- | -------------------------- | -------------- |
| **Tools**     | Agent   | Actions, data access, auth | ✅ Universal    |
| **Resources** | User    | Config, profiles, context  | ⚠️ Limited     |
| **Prompts**   | Both    | Instructions, guidelines   | ⚠️ Limited     |

**Key insight:** Tools are LLM-focused (agent-driven). Resources and Prompts are UI-focused (user-driven). Build for Tools first, enhance with Resources/Prompts for supporting clients.

<CardGroup cols={2}>
  <Card title="Tools Deep Dive" icon="wrench" href="/core-concepts/tools">
    Learn about MCP tools
  </Card>

  <Card title="Resources Guide" icon="database" href="/core-concepts/resources">
    Understanding resources
  </Card>
</CardGroup>