Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@amanahfy-ai-mcp Look up the campaign gaza-100k-in-72hrs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A production-ready Model Context Protocol (MCP) server that provides AI tools & resources with access to Amanahfy APIs & services. Built with TypeScript and following clean architecture principles.
Dual Transport Support: STDIO (Claude Desktop) and HTTP (testing/development)
Clean Architecture: 5-layer architecture with separation of concerns
CLI Tools: Command-line interface for direct API testing
Resource Access: URI-based resource references (campaign://slug, ip://address)
Type Safety: Full TypeScript implementation with Zod validation
Related MCP server: mcp-ip2location
Node.js (>=18.0.0): Download
Git: For version control
Claude Desktop: For MCP integration (Optional)
# Clone the repository
git clone <your-repo-url>
cd amanahfy-ai-mcp
# Install dependencies
npm install
# Build the project
npm run buildAdd to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"amanahfy-ai-mcp": {
"command": "node",
"args": [
"C:\\path\\to\\campaign-agent-mcp-server\\dist\\index.js"
],
"env": {
"TRANSPORT_MODE": "stdio"
}
}
}
}Restart Claude Desktop completely, then ask Claude:
"Look up the campaign gaza-100k-in-72hrs"
"What's the location of IP 8.8.8.8?"
Test functionality directly from the command line:
# Get campaign details
npm run cli -- get-campaign-details gaza-100k-in-72hrs
# With custom options
npm run cli -- get-campaign-details gaza-100k-in-72hrs --timeout 5000 --retries 1The server follows a clean 5-layer architecture:
├── CLI Layer (src/cli/) # Command-line interfaces
├── Tools Layer (src/tools/) # MCP tool definitions
├── Resources Layer (src/resources/) # MCP resource handlers
├── Controllers Layer (src/controllers/) # Business logic
├── Services Layer (src/services/) # External API integration
└── Utils Layer (src/utils/) # Shared utilitiesCreate a .env file in the project root:
# Transport Configuration
TRANSPORT_MODE=stdio
PORT=8000
DEBUG=false
NODE_ENV=production
# API Configuration
AMANAHFY_API_BASE=https://api.amanahfy.com/api
# Optional API Keys
# IPAPI_API_TOKEN=your_api_token_here# Development
npm run build # Compile TypeScript
npm run dev:stdio # Run in STDIO mode with debug
npm run dev:http # Run in HTTP mode with debug
# MCP Server Modes
npm run mcp:stdio # STDIO transport (for Claude Desktop)
npm run mcp:http # HTTP transport (for testing)
# Testing & Development
npm run cli # CLI mode
npm run test # Run tests
npm run lint # Run ESLint
npm run format # Format with Prettier
# Debugging
npm run mcp:inspect # Launch with MCP InspectorTest your MCP server with the official inspector:
# Launch server with inspector
npm run mcp:inspect
# Then open: http://localhost:3000/mcp# Test HTTP mode
npm run mcp:http
# Test specific endpoints
curl http://localhost:8000/mcp# Test campaign lookup
npm run cli -- get-campaign-details gaza-100k-in-72hrs
# Test IP lookup
npm run cli -- get-ip-details 8.8.8.8"Not valid JSON" error
Ensure no console output is interfering with STDIO mode
Check that TRANSPORT_MODE=stdio in Claude Desktop config
Module not found errors
Run npm run build after any code changes
Verify all dependencies are installed: npm install
API timeout errors
Check network connectivity
Increase timeout values in tool parameters
Verify API endpoints are accessible
Claude Desktop connection issues
Use absolute paths in config
Restart Claude Desktop completely after config changes
Check Claude Desktop logs for detailed error messages
Enable detailed logging:
DEBUG=true
NODE_ENV=developmentNeed help? Open an issue or check the troubleshooting section above.
Retrieves detailed information about a donation campaign from Amanahfy by campaign slug. Returns comprehensive campaign data including fundraising progress, organization details, timeline, and campaign features. Use this tool to get current information about active fundraising campaigns. Example slug: "gaza-100k-in-72hrs". Configure timeout and retries for reliability.
| Name | Required | Description | Default |
|---|---|---|---|
| retries | No | Number of retry attempts (0-5) | |
| timeout | No | Request timeout in milliseconds (1000-30000) | |
| campaignSlug | Yes | Campaign slug identifier (e.g., "gaza-100k-in-72hrs") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses return content (fundraising progress, organization details, timeline, features) and hints at reliability needs via timeout/retries. However, it doesn't mention auth requirements, error handling, or invalid slug behavior, which would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and return summary, no redundant phrasing. Each sentence serves a distinct function: what, what returns, when and how to use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description covers return content, usage, and parameters well. It lacks notes on errors or edge cases, but given the tool's simplicity, it's nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds an example slug and explains the purpose of timeout/retries for reliability, but this is marginal beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieves' and the specific resource 'donation campaign from Amanahfy by campaign slug'. It distinguishes itself from the sibling tool ip_get_details by focusing on campaigns, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this tool to get current information about active fundraising campaigns', providing clear usage context. It doesn't mention alternatives, but the sibling is obviously for IP details, so no confusion exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves detailed geolocation and network information for a public IP address (ipAddress). If no IP is provided, automatically uses the server's current public IP. Returns comprehensive location data including country, region, city, coordinates, timezone, and network details like ISP and organization. Use includeExtendedData to get additional information such as ASN, mobile/proxy detection (requires API token). Note: Cannot lookup private IPs (e.g., 192.168.x.x, 10.x.x.x). Powered by ip-api.com. Enable useHttps for secure connections (required for paid tier).
| Name | Required | Description | Default |
|---|---|---|---|
| useHttps | No | Whether to use HTTPS for the API call (recommended). | |
| ipAddress | No | IP address to lookup (omit for current IP) | |
| includeExtendedData | No | Whether to include extended data (ASN, host, organization, etc.). Requires API token. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behavioral traits: the external dependency ('Powered by ip-api.com'), the limitation on private IPs, the automatic use of server IP when omitted, and the token requirement for extended data. It does not mention error handling or rate limits, but the core behavior is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences long, with each sentence adding new information: purpose, fallback behavior, return data, extended data, limitation, and external service. The main purpose is front-loaded, and there is no redundant repetition of schema text. Very concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description does a good job of conveying expected results: it lists return data categories (country, region, city, coordinates, timezone, ISP, organization) and extended fields. It also covers setup requirements (HTTPS, token) and limitations (private IPs). Minor gaps include lack of error response or rate limit information, but for a straightforward lookup, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of the three parameters with descriptions. The tool description adds meaningful context beyond the schema: includeExtendedData specifically yields ASN/mobile/proxy detection and requires a token; useHttps is required for paid tier; ipAddress omission uses the current IP. This enriches the bare schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's function: 'Retrieves detailed geolocation and network information for a public IP address.' It also specifies the optional behavior when no IP is provided. This clearly distinguishes it from the sibling tool campaign_get_details, which is unrelated in domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: it describes the automatic fallback to the server's IP, notes the need for an API token for extended data, and mentions the HTTPS requirement for paid tier. It also explicitly states a limitation: 'Cannot lookup private IPs.' However, it does not explicitly name alternative tools, though the sibling domain is distinctly different.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0campaign_get_detailsip_get_detailsScored across 2 tools
The two tools are entirely unrelated in purpose: one handles IP geolocation and the other retrieves campaign details. There is zero overlap or ambiguity between them.
Both tools follow the same 'get_details' verb-noun pattern with clear prefixes ('ip' and 'campaign'), creating a consistent and predictable naming convention.
With only 2 tools, the server feels thin. While each tool is distinct, the low count is borderline for a server that appears to cover two separate domains.
Each domain is only minimally covered: IP lookup has no additional operations beyond details, and campaigns similarly lack listing or mutation endpoints. The server leaves significant gaps for any broader workflow.
Utility tools for AI agents: hashing, text stats, validation, DNS, currency, GEO audits.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Marketing intelligence API for AI agents. Real campaign data, not LLM guesses.
