Dictionary MCP Server

Dictionary MCP Server

Dictionary and thesaurus MCP server exposing Free Dictionary API via Streamable HTTP on Apify. Provides tools to define words, fetch example usage, and list synonyms.

About this MCP Server: To understand how to connect to and utilize this MCP server, see the official Model Context Protocol documentation at mcp.apify.com.

Source MCP server: casual-mcp-server-words (Python, stdio), published as a pip tool.

Credits: All credits to the original authors of the source server. 🚩 Claim this MCP server – write to ai@apify.com.

Connection URL

MCP clients can connect to this server at:

https://mcp-servers--dictionary-mcp-server.apify.actor/mcp

Client Configuration

To connect to this MCP server, use the following configuration in your MCP client:

{
    "mcpServers": {
        "dictionary": {
            "type": "http",
            "url": "https://mcp-servers--dictionary-mcp-server.apify.actor/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_APIFY_TOKEN"
            }
        }
    }
}

Note: Replace YOUR_APIFY_TOKEN with your actual Apify API token. You can find your token in the Apify Console.

💰 Pricing

This template uses the Pay Per Event (PPE) monetization model, which provides flexible pricing based on defined events.

Charging strategy options

The template supports multiple charging approaches that you can customize based on your needs:

1. Generic MCP charging

Charge for standard MCP operations with flat rates:

{
    "apify-actor-start": {
        "eventTitle": "Synthetic Actor start (covered first 5s)",
        "eventDescription": "Synthetic start event charged automatically by Apify. Do not charge manually in code.",
        "eventPriceUsd": 0.00005
    },
    "tool-list": {
        "eventTitle": "MCP tool listing",
        "eventDescription": "Fee for listing available tools",
        "eventPriceUsd": 0.0001
    },
    "tool-call": {
        "eventTitle": "MCP tool call",
        "eventDescription": "Fee for executing MCP tools",
        "eventPriceUsd": 0.05
    },
    "resource-read": {
        "eventTitle": "MCP resource access",
        "eventDescription": "Fee for accessing full content or resources",
        "eventPriceUsd": 0.0001
    },
    "prompt-get": {
        "eventTitle": "MCP prompt processing",
        "eventDescription": "Fee for processing AI prompts",
        "eventPriceUsd": 0.0001
    }
}

2. Domain-specific charging (Words)

Charge per tool based on functionality:

{
    "apify-actor-start": {
        "eventTitle": "Synthetic Actor start (covered first 5s)",
        "eventDescription": "Synthetic start event charged automatically by Apify. Do not charge manually in code.",
        "eventPriceUsd": 0.00005
    },
    "define": {
        "eventTitle": "Word definition lookup",
        "eventDescription": "Fee for retrieving definitions",
        "eventPriceUsd": 0.001
    },
    "example_usage": {
        "eventTitle": "Example usage lookup",
        "eventDescription": "Fee for retrieving example sentences",
        "eventPriceUsd": 0.001
    },
    "synonyms": {
        "eventTitle": "Synonyms lookup",
        "eventDescription": "Fee for retrieving synonyms",
        "eventPriceUsd": 0.001
    }
}

3. No charging (free service)

Comment out all charging lines in the code for a free service.

How to implement charging

1. Define your events in .actor/pay_per_event.json (see examples above). This file is not actually used at Apify platform but serves as a reference.

2. Enable charging in code by uncommenting the appropriate lines in src/mcp_gateway.py:

   # For generic charging:
   await charge_mcp_operation(actor_charge_function, ChargeEvents.TOOL_CALL)
   
   # For domain-specific charging:
   if tool_name == 'search_papers':
       await charge_mcp_operation(actor_charge_function, ChargeEvents.SEARCH_PAPERS)
   

3. Add custom events to src/const.py if needed:

   class ChargeEvents(str, Enum):
       # Your custom events
       CUSTOM_OPERATION = 'custom-operation'
   

4. Set up PPE model on Apify:

   • Go to your Actor's Publication settings
   • Set the Pricing model to Pay per event
   • Add your pricing schema from pay_per_event.json

Authorized tools

This template includes tool authorization - only tools listed in src/const.py can be executed:

Note: The TOOL_WHITELIST dictionary only applies to tools (executable functions). Prompts (like deep-paper-analysis) are handled separately and don't need to be added to this list.

Tool whitelist for MCP server Only tools listed here will be present to the user and allowed to execute. Format of the dictionary: {tool_name: (charge_event_name, default_count)} To add new authorized tools, add an entry with the tool name and its charging configuration.

TOOL_WHITELIST = {
    ChargeEvents.DEFINE.value: (ChargeEvents.DEFINE.value, 1),
    ChargeEvents.EXAMPLE_USAGE.value: (ChargeEvents.EXAMPLE_USAGE.value, 1),
    ChargeEvents.SYNONYMS.value: (ChargeEvents.SYNONYMS.value, 1),
}

To add new tools:

1. Add charge event to ChargeEvents enum
2. Add tool entry to TOOL_WHITELIST dictionary with format: tool_name: (event_name, count)
3. Update pricing in pay_per_event.json
4. Update pricing at Apify platform

Unauthorized tools are blocked with clear error messages.

🔧 How it works

This template implements a MCP gateway that can connect to a stdio-based, Streamable HTTP, or SSE-based MCP server and expose it via Streamable HTTP transport. Here's how it works:

Server types

1. Stdio server (StdioServerParameters):
   • Spawns a local process that implements the MCP protocol over stdio.
   • Configure using the command parameter to specify the executable and the args parameter for additional arguments.
   • Optionally, use the env parameter to pass environment variables to the process.

Example:

server_type = ServerType.STDIO
MCP_SERVER_PARAMS = StdioServerParameters(
    command='casual-mcp-server-words',
    args=[],
    env={},  # Optional environment variables
)

2. Remote server (RemoteServerParameters):
   • Connects to a remote MCP server via HTTP or SSE transport.
   • Configure using the url parameter to specify the server's endpoint.
   • Set the appropriate server_type (ServerType.HTTP or ServerType.SSE).
   • Optionally, use the headers parameter to include custom headers (e.g., for authentication) and the auth parameter for additional authentication mechanisms.

Example:

server_type = ServerType.HTTP
MCP_SERVER_PARAMS = RemoteServerParameters(
    url='https://mcp.apify.com',
    headers={'Authorization': 'Bearer YOUR-API-KEY'},  # Replace with your authentication token
)

Note: SSE transport is also supported by setting server_type = ServerType.SSE.

• Tips:
  • Ensure the remote server supports the transport type you're using and is accessible from the Actor's environment.
  • Use environment variables to securely store sensitive information like tokens or API keys.

Environment variables:

Environment variables can be securely stored and managed at the Actor level on the Apify platform. These variables are automatically injected into the Actor's runtime environment, allowing you to:

• Keep sensitive information like API keys secure.
• Simplify configuration by avoiding hardcoded values in your code.

Gateway implementation

The MCP gateway (create_gateway function) handles:

• Creating a Starlette web server with Streamable HTTP (/mcp) endpoint
• Managing connections to the underlying MCP server
• Forwarding requests and responses between clients and the MCP server
• Handling charging through the actor_charge_function (Actor.charge in Apify Actors)
• Tool authorization: Only allowing whitelisted tools to execute
• Access control: Blocking unauthorized tool calls with clear error messages

Key components:

• create_gateway: Creates an MCP server instance that acts as a gateway
• charge_mcp_operation: Handles charging for different MCP operations
• TOOL_WHITELIST: Dictionary mapping tool names to (event_name, count) tuples for authorization and charging

MCP operations

The MCP gateway supports all standard MCP operations:

• list_tools(): List available tools
• call_tool(): Execute a tool with arguments
• list_prompts(): List available prompts
• get_prompt(): Get a specific prompt
• list_resources(): List available resources
• read_resource(): Read a specific resource

Each operation can be configured for charging in the PPE model.

📚 Resources

• What is Anthropic's Model Context Protocol?
• How to use MCP with Apify Actors
• Apify MCP server
• Apify MCP server documentation
• Apify MCP client
• MCP Servers hosted at Apify
• Model Context Protocol documentation
• Apify SDK documentation

Getting started

For complete information see this article. To run the Actor use the following command:

$apify run

Deploy to Apify

Connect Git repository to Apify

If you've created a Git repository for the project, you can easily connect to Apify:

1. Go to Actor creation page
2. Click on Link Git Repository button

Push project on your local machine to Apify

You can also deploy the project on your local machine to Apify without the need for the Git repository.

1. Log in to Apify. You will need to provide your Apify API Token to complete this action.

   $apify login
   

2. Deploy your Actor. This command will deploy and build the Actor on the Apify Platform. You can find your newly created Actor under Actors -> My Actors.

   $apify push
   

Documentation reference

To learn more about Apify and Actors, take a look at the following resources:

• Apify SDK for JavaScript documentation
• Apify SDK for Python documentation
• Apify Platform documentation
• Join our developer community on Discord