Skip to main content

Core Concepts

Understand the fundamental building blocks of Reeva.

MCP Protocol​

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources.

What is MCP?​

MCP defines how AI models interact with tools through a JSON-RPC based protocol. It specifies:

  • Tool discovery: How clients learn what tools are available
  • Tool execution: How tools are invoked with parameters
  • Response handling: How results are returned and displayed

Why MCP?​

  • Standardized: One protocol works across multiple AI clients
  • Extensible: Easy to add new tools and capabilities
  • Secure: Built-in authentication and permission models
  • Efficient: Optimized for real-time AI interactions

MCP in Reeva​

Reeva builds true MCP servers. Your servers:

  • Speak native MCP protocol
  • Work with any MCP-compatible client
  • Support all MCP methods (tools/list, tools/call, etc.)
  • Handle streaming responses
  • Manage credentials securely

Servers​

A Server is a collection of tools exposed through the MCP protocol.

Anatomy of a Server​

Server: "My Productivity Server"
├── Custom Tool: "My Notion Search"
├── Custom Tool: "My Jira Tickets"
└── Custom Tool: "My Gmail"

Each server:

  • Has a unique Server ID (e.g., server_abc123)
  • Contains multiple Custom Tools
  • Has one or more API Keys for authentication
  • Can be accessed via REST API or MCP protocol
  • Logs usage and analytics

Server Use Cases​

Single-Purpose Servers

  • Research Server (Perplexity, Web Search, Firecrawl)
  • Productivity Server (Notion, Jira, Gmail)
  • Data Server (Supabase, PostgreSQL)

Multi-Purpose Servers

  • Personal Assistant (mix of all tools you need)
  • Project-Specific (tools for a specific project)

Server Management​

Servers can be:

  • Created through the dashboard or API
  • Updated to add/remove tools
  • Tested in Chat or Playground
  • Deployed to multiple IDEs simultaneously
  • Deleted when no longer needed

Tools​

Tools are the base integrations provided by Reeva.

Base Tools​

These are the 50+ integrations built and maintained by Reeva:

  • firecrawl_scrape: Scrape webpage content
  • notion_search_pages: Search Notion workspace
  • google_search: Search Google
  • jira_create_issue: Create Jira ticket
  • And many more...

Each base tool has:

  • Name: Unique identifier
  • Description: What it does
  • Input Schema: Required and optional parameters
  • Output Schema: What it returns
  • Credential Requirements: What authentication is needed
  • Credit Cost: How many credits it consumes

Tool Categories​

Tools are organized by category:

  • Web Scraping: Firecrawl, Apify
  • Productivity: Notion, Jira
  • Search: Google, DuckDuckGo, Perplexity
  • Workflow: N8N
  • Database: Supabase, PostgreSQL
  • AI: Perplexity, OpenAI (upcoming)
  • Utilities: Math, Text, Time

Custom Tools​

Custom Tools are your configured instances of base tools.

Why Custom Tools?​

Base tools are generic. Custom tools let you:

  • Set default parameters: Pre-fill common values
  • Link credentials: Connect your accounts
  • Name descriptively: "My Company Notion" vs "notion_search"
  • Reuse configurations: Use the same tool in multiple servers

Creating Custom Tools​

Base Tool: google_search
     ↓
Custom Tool: "My Web Search"
├── Parameter Overrides: {num_results: 5}
├── Credentials: (none needed)
└── Used in: 3 servers

Custom Tool Workflow​

  1. Select a base tool from the catalog
  2. Configure parameters (optional overrides)
  3. Link credentials (if required)
  4. Name and describe your custom tool
  5. Add to servers as needed

Example​

Base Tool: firecrawl_scrape

  • Input: url, formats, onlyMainContent
  • Generic, unconfigured

Custom Tool: "Blog Content Scraper"

  • Parameters: formats: ["markdown"], onlyMainContent: true
  • Credential: My Firecrawl API key
  • Purpose: Extract blog post content as markdown

Authentication​

MCP Server Authentication​

All MCP servers use API keys for authentication. This is the only authentication method for accessing your servers from IDEs and applications.

Server-Specific Keys

  • Tied to a single server
  • Format: mcpk_xxxxxxxxxxxxx
  • Ideal for production deployments
  • Created per-server in the dashboard

Global Keys

  • Access multiple servers (when linked)
  • Useful for development environments
  • Created in the API Keys section
  • Must be linked to each server

Service Credentials (Accounts)​

Some tools require authentication to external services (Notion, Jira, Firecrawl, etc.). You manage these separately in the Accounts section:

  • Create accounts by linking services (OAuth or API keys)
  • Associate accounts with custom tools
  • Rotate credentials without updating tools
  • Revoke access at any time

Authentication Flow​

IDE (Cursor) → MCP API Key → Reeva Server → Custom Tool → Service Credential → External Service (Notion)

Key Points:

  • MCP API keys authenticate your IDE to Reeva servers
  • Service credentials authenticate Reeva to external services
  • These are separate and serve different purposes

Credits​

Reeva uses a credit-based pricing model for fair usage.

How Credits Work​

  • Each tool execution costs credits (typically 1-5)
  • Cost depends on tool complexity and external API usage
  • Credits are deducted before execution
  • Insufficient credits block execution (fail-safe)

Credit Costs​

Examples:

  • Web Search: 1 credit
  • Firecrawl Scrape: 3 credits
  • Notion Search: 1 credit
  • Perplexity Ask: 2 credits

See Credit Pricing for complete list.

Purchasing Credits​

  • One-time packages: 100, 500, 1000, 5000 credits
  • Subscriptions: Monthly credit allowance
  • Never expire: Credits roll over indefinitely

See Pricing for details.

Execution Flow​

Here's what happens when AI uses your tool:

1. AI Agent sends tool call → MCP Server
2. Server authenticates → API Key validated
3. Server resolves → Custom Tool → Base Tool
4. Server checks → Credits available?
5. Server deducts → Credits from balance
6. Server injects → Account credentials (if needed)
7. Tool executes → External API called
8. Results returned → To AI Agent
9. Usage logged → Analytics & billing

Architecture Overview​

┌─────────────────────────────────────────┐
│           Your IDE (Cursor)             │
│  ┌────────────────────────────────────┐ │
│  │     AI Agent + MCP Client          │ │
│  └────────────────┬───────────────────┘ │
└───────────────────┼─────────────────────┘
                    │ MCP Protocol
                    ↓
┌───────────────────────────────────────────┐
│          Reeva Platform                   │
│  ┌─────────────────────────────────────┐ │
│  │    MCP Server (your server)         │ │
│  │  ┌──────────┐  ┌──────────┐        │ │
│  │  │Custom    │  │Custom    │        │ │
│  │  │Tool 1    │  │Tool 2    │        │ │
│  │  └────┬─────┘  └────┬─────┘        │ │
│  └───────┼─────────────┼──────────────┘ │
│          │             │                 │
│  ┌───────▼─────────────▼──────────────┐ │
│  │    Base Tools (50+)                 │ │
│  └──────────────┬──────────────────────┘ │
└─────────────────┼────────────────────────┘
                  │
                  ↓
        External Services
    (Notion, Jira, Firecrawl, etc.)

Best Practices​

Server Design​

  • Keep servers focused: Group related tools
  • Use descriptive names: "Research Server" not "Server 1"
  • Test before deploying: Use Chat/Playground
  • Monitor usage: Track which tools are used most

Custom Tools​

  • Name clearly: Describe purpose, not just service
  • Document overrides: Note why you set specific defaults
  • Reuse when possible: Don't duplicate custom tools
  • Link correct credentials: Test authentication

Security​

  • Rotate API keys: Update keys periodically
  • Use server-specific keys: Don't share global keys
  • Limit scope: Only grant necessary permissions
  • Revoke unused keys: Clean up old keys

Cost Management​

  • Monitor credit usage: Check dashboard regularly
  • Set alerts: Get notified of high usage
  • Optimize calls: Reduce unnecessary tool executions
  • Buy subscriptions: Save on high-volume usage

Next Steps​

Now that you understand the concepts, try: