NudgeLang Documentation
Components
MCP Servers

MCP Servers

MCP Servers

The Model Context Protocol (MCP) allows NudgeLang to connect with external services that provide prompts, resources, and tools following the MCP specification.

Basic Structure 

mcp_servers:
  - id: knowledge_base
    endpoint: "https://api.example.com/kb"
    description: "Product knowledge base with documentation and FAQs"
    capabilities:
      resources: 
        subscribe: true
        listChanged: true
      prompts: 
        listChanged: true
      tools: 
        listChanged: true
    auth:
      type: "bearer"
      token_env: "KB_API_TOKEN"

Server Types

1. Knowledge Base 

mcp_servers:
  - id: product_knowledge
    type: retrieval
    endpoint: "https://api.example.com/products"
    capabilities:
      resources: true
      prompts: true
    auth:
      type: "bearer"
      token_env: "KB_API_TOKEN"

2. Database 

mcp_servers:
  - id: customer_data
    type: database
    endpoint: "https://api.example.com/customers"
    capabilities:
      resources: true
      tools: true
    auth:
      type: "basic"
      username_env: "DB_USERNAME"
      password_env: "DB_PASSWORD"

3. Custom Server 

mcp_servers:
  - id: custom_server
    type: custom
    endpoint: "https://api.example.com/mcp"
    capabilities:
      resources: true
      prompts: true
      tools: true
    auth:
      type: "custom"
      headers:
        X-API-Key: "${env.CUSTOM_API_KEY}"

Capabilities

1. Resources

Resources are application-controlled data that provides context to the model:

capabilities:
  resources:
    subscribe: true  # Subscribe to changes
    listChanged: true  # Get notifications when available resources change

2. Prompts

Prompts are user-controlled templates that guide LLM interactions:

capabilities:
  prompts:
    listChanged: true  # Get notifications when available prompts change

3. Tools

Tools are model-controlled functions that allow the LLM to perform actions. MCP servers can provide tools that your agent can use to interact with external services. These tools are defined on the server side and can be discovered and used by your agent through the MCP protocol.

capabilities:
  tools:
    listChanged: true  # Get notifications when available tools change
    discover: true     # Allow discovery of available tools
    execute: true      # Allow execution of tools

When a server provides tools capability, your agent can:

  1. Discover available tools through the MCP protocol
  2. Get tool definitions including parameters and descriptions
  3. Execute tools with appropriate parameters
  4. Receive tool execution results

This allows for seamless integration of external services while maintaining a consistent interface in your agent.

Authentication

1. Bearer Token 

auth:
  type: "bearer"
  token_env: "API_TOKEN"

2. Basic Auth 

auth:
  type: "basic"
  username_env: "USERNAME"
  password_env: "PASSWORD"

3. API Key 

auth:
  type: "api_key"
  key_env: "API_KEY"
  header: "X-API-Key"

Resource Management

1. Subscribing to Resources 

mcp_servers:
  - id: knowledge_base
    endpoint: "https://api.example.com/kb"
    capabilities:
      resources:
        subscribe: true
    resources:
      - uri: "file:///kb/product_docs.md"
        type: "markdown"
      - uri: "file:///kb/faq.json"
        type: "json"

2. Resource Types 

resources:
  - uri: "file:///docs/manual.pdf"
    type: "pdf"
  - uri: "file:///data/schema.json"
    type: "json"
  - uri: "file:///kb/articles/*.md"
    type: "markdown"
    pattern: "*.md"

Complete Example

Here’s a complete MCP server configuration:

mcp_servers:
  - id: knowledge_base
    type: retrieval
    endpoint: "https://api.example.com/kb"
    description: "Product knowledge base"
    capabilities:
      resources:
        subscribe: true
        listChanged: true
      prompts:
        listChanged: true
      tools:
        listChanged: true
    auth:
      type: "bearer"
      token_env: "KB_API_TOKEN"
    resources:
      - uri: "file:///kb/product_docs.md"
        type: "markdown"
      - uri: "file:///kb/faq.json"
        type: "json"
    prompts:
      - name: "product_information"
        template: |
          Provide information about the following product:
          {product_name}          
    tools:
      - name: "search_products"
        description: "Search for products"
        parameters:
          - name: query
            type: string
            required: true

Best Practices

  1. Security: Use environment variables for sensitive credentials
  2. Resource Management: Subscribe only to necessary resources
  3. Error Handling: Implement proper error handling for server failures
  4. Caching: Cache resources when appropriate
  5. Monitoring: Monitor server health and performance
  6. Documentation: Document server capabilities and requirements

Next Steps

Last updated on
ModelsTools