Content
# App2Chat MCP Template
> **Public Template** for creating MCP (Model Context Protocol) servers compatible with the [App2Chat](https://app2chat.io) marketplace
This template provides the structure and compatibility requirements for developing MCP servers that can be integrated into the [App2Chat](https://app2chat.io) platform.
## 🌟 What is App2Chat?
[App2Chat](https://app2chat.io) is an AI-powered conversational API platform that makes it possible for any API to operate as a conversational contact on WhatsApp, Telegram, Discord, and other messaging platforms.
### The App2Chat MCP Marketplace
The **MCP Marketplace** is a curated collection of third-party API integrations that extend the capabilities of App2Chat bots. Instead of just calling your own API endpoints, users can enhance their bots third-party APIs integrated in their AI bots via MCP Servers.
**Setup is simple:** Upload an OpenAPI file → Select marketplace MCPs → Get an AI-powered chatbot that can interact with multiple APIs through natural conversation.
[App2Chat](https://app2chat.io) handles all deployment, infrastructure, and transport protocols - you focus on your API integration.
## 🎯 What This Template Provides
- ✅ **[App2Chat](https://app2chat.io) Compatible Structure** - Follows exact requirements for marketplace integration
- ✅ **Transport Protocol Compatibility** - Works with [App2Chat's](https://app2chat.io) internal transport layer
- ✅ **Standardized Error Handling** - Proper error formatting and classification
- ✅ **Tool Naming Conventions** - Required naming patterns for tool discovery
- ✅ **Testing Framework** - Validate compatibility before submission
- ✅ **No Infrastructure Complexity** - Focus purely on your API logic
## 🚀 Quick Start
### 1. Use This Template
```bash
git clone https://github.com/app2chat/public-marketplace-mcp-template.git your-api-mcp
cd your-api-mcp
```
### 2. Customize Your Integration
Replace these placeholders in `src/mcp-server.js`:
| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{{API_NAME}}` | API name (lowercase, no spaces) | `weather`, `finance`, `notebook` |
| `{{API_BASE_URL}}` | Your API's base URL | `https://api.mydomain.com` |
### 3. Implement Your API Tools
In the `createTools()` method, replace example tools with your API endpoints:
```javascript
createTools() {
return {
// REQUIRED: Tool names must be prefixed with your API name
[`${this.apiName}_get_repositories`]: {
description: "List user repositories",
inputSchema: {
type: "object",
properties: {
user: { type: "string", description: "GitHub username" },
type: { type: "string", enum: ["public", "private", "all"] }
},
required: ["user"]
},
handler: async (params) => {
try {
const response = await this.makeAPIRequest('GET', `/users/${params.user}/repos`, params);
return this.formatSuccessResponse(response);
} catch (error) {
return this.formatErrorResponse(`${this.apiName}_get_repositories`, error);
}
}
},
// Add more tools...
};
}
```
### 4. Configure Authentication
Update the `getAuthHeaders()` method for your API's authentication:
```javascript
getAuthHeaders() {
return {
// Choose your API's authentication method:
'Authorization': `Bearer ${this.apiKey}`, // Bearer token
// 'X-API-KEY': this.apiKey, // API key header
// 'Authorization': `Basic ${btoa(this.apiKey + ':')}`, // Basic auth
'User-Agent': `App2Chat-${this.apiName}-MCP/${this.version}`,
'Accept': 'application/json'
};
}
```
### 5. Test Your Integration
```bash
npm test
```
This validates App2Chat compatibility requirements.
## 📋 [App2Chat](https://app2chat.io) Requirements
### ✅ Tool Naming Convention
- **REQUIRED**: All tools must be prefixed with your API name
- Format: `${apiName}_action_resource`
- Examples: `weather_get_forecast`, `finance_get_balance`, `notebook_create_page`
### ✅ Response Format
- **Success responses**: Use `formatSuccessResponse(data)`
- **Error responses**: Use `formatErrorResponse(toolName, error)` with `isError: true`
### ✅ Required Methods
Your MCP class must implement these methods (included in template):
- `handleMCPRequest(request)` - Process JSON-RPC requests
- `getServerInfo()` - Provide server metadata
- `validateConfiguration()` - Validate setup
### ✅ Input Schemas
All tools must have complete input schemas:
```javascript
inputSchema: {
type: "object",
properties: {
param_name: {
type: "string",
description: "Clear parameter description"
}
},
required: ["param_name"]
}
```
## 🔧 Template Structure
```
📁 your-api-mcp/
├── 📄 src/mcp-server.js # Main MCP server class
├── 📄 test/test-mcp.js # Compatibility test suite
├── 📄 package.json # Package configuration
├── 📄 README.md # This documentation
└── 📄 examples/ # Usage examples (optional)
```
## 🧪 Testing and Validation
### Run Compatibility Tests
```bash
npm test
```
This test suite validates:
- ✅ Tool naming conventions
- ✅ Response formats
- ✅ Error handling
- ✅ Configuration completeness
- ✅ JSON-RPC protocol compliance
### Test Coverage
The test framework checks:
- Server initialization
- Tool discovery (`tools/list`)
- Tool execution (`tools/call`)
- Error handling for invalid tools
- Configuration validation
- Naming convention compliance
## 🎨 API Integration Patterns
### GET Endpoints
```javascript
[`${this.apiName}_get_data`]: {
handler: async (params) => {
try {
const response = await this.makeAPIRequest('GET', '/endpoint', params);
return this.formatSuccessResponse(response);
} catch (error) {
return this.formatErrorResponse('tool_name', error);
}
}
}
```
### POST Endpoints
```javascript
[`${this.apiName}_create_resource`]: {
handler: async (params) => {
try {
const response = await this.makeAPIRequest('POST', '/endpoint', params);
return this.formatSuccessResponse(response);
} catch (error) {
return this.formatErrorResponse('tool_name', error);
}
}
}
```
### Authentication Patterns
#### Bearer Token
```javascript
getAuthHeaders() {
return {
'Authorization': `Bearer ${this.apiKey}`,
'Accept': 'application/json'
};
}
```
#### API Key Header
```javascript
getAuthHeaders() {
return {
'X-API-KEY': this.apiKey,
'Accept': 'application/json'
};
}
```
#### Basic Authentication
```javascript
getAuthHeaders() {
return {
'Authorization': `Basic ${btoa(this.apiKey + ':')}`,
'Accept': 'application/json'
};
}
```
## 🛡️ Error Handling Best Practices
### API Error Parsing
Customize `handleAPIError()` for your API's error format:
```javascript
async handleAPIError(response) {
const errorText = await response.text();
let errorMessage;
try {
const errorJson = JSON.parse(errorText);
// Adapt to your API's error structure
errorMessage = errorJson.error?.message ||
errorJson.message ||
'Unknown error';
} catch {
errorMessage = errorText || `HTTP ${response.status} error`;
}
throw new Error(`${this.apiName} API error (${response.status}): ${errorMessage}`);
}
```
### Error Response Format
Always use the standardized error format:
```javascript
return {
content: [{
type: "text",
text: `Error message here`
}],
isError: true // REQUIRED for App2Chat error detection
};
```
## 📤 Submitting to [App2Chat](https://app2chat.io) Marketplace
### Prerequisites
1. ✅ All tests pass (`npm test`)
2. ✅ Real API testing completed
3. ✅ Documentation is complete
4. ✅ No placeholder values remain
### Submission Process
1. **Package Your MCP**: Ensure your code follows this template structure
2. **Submit via GitHub**: Create a public repository with your MCP
3. **[App2Chat](https://app2chat.io) Review**: Our team will review for compatibility and security
4. **Integration**: Once approved, [App2Chat](https://app2chat.io) handles all deployment and infrastructure
5. **Marketplace**: Your MCP becomes available to [App2Chat](https://app2chat.io) users
### What [App2Chat](https://app2chat.io) Handles
- ✅ **Deployment Infrastructure** - Cloudflare Workers, serverless scaling
- ✅ **Transport Protocols** - HTTP, WebSocket, and internal routing
- ✅ **Authentication** - User API key management and security
- ✅ **Monitoring** - Health checks, error tracking, performance metrics
- ✅ **Updates** - Automatic deployment of approved updates
### What You Provide
- ✅ **MCP Server Logic** - Your API integration following this template
- ✅ **Tool Definitions** - Complete input schemas and descriptions
- ✅ **Error Handling** - Proper error formatting and classification
- ✅ **Documentation** - Clear setup and usage instructions
## 🔍 Example Implementation
See how a real API integration looks:
```javascript
class GitHubMCPServer extends App2ChatMCPServer {
constructor(apiKey) {
super(apiKey);
this.apiName = 'github';
this.baseUrl = 'https://api.github.com';
}
createTools() {
return {
github_get_user: {
description: "Get GitHub user information",
inputSchema: {
type: "object",
properties: {
username: { type: "string", description: "GitHub username" }
},
required: ["username"]
},
handler: async (params) => {
try {
const response = await this.makeAPIRequest('GET', `/users/${params.username}`);
return this.formatSuccessResponse(response);
} catch (error) {
return this.formatErrorResponse('github_get_user', error);
}
}
}
};
}
getAuthHeaders() {
return {
'Authorization': `token ${this.apiKey}`,
'Accept': 'application/vnd.github.v3+json',
'User-Agent': `App2Chat-github-MCP/${this.version}`
};
}
}
```
## ❓ Frequently Asked Questions
### Q: Do I need to handle deployment?
**A: No!** [App2Chat](https://app2chat.io) handles all deployment, infrastructure, and scaling. You only provide the MCP server logic.
### Q: What transport protocols do I need to support?
**A: None!** [App2Chat's](https://app2chat.io) transport layer handles HTTP, WebSocket, and internal routing. Your MCP just needs to implement the `handleMCPRequest` method.
### Q: How are user API keys managed?
**A: [App2Chat](https://app2chat.io) handles this.** Users enter their API keys in the [App2Chat](https://app2chat.io) interface, and they're securely passed to your MCP server constructor.
### Q: Can I use external dependencies?
**A: Yes, but minimize them.** [App2Chat](https://app2chat.io) will review all dependencies for security. Prefer built-in Node.js features when possible.
### Q: How do I update my MCP?
**A: Submit updates via GitHub.** [App2Chat](https://app2chat.io) will review and deploy approved updates automatically.
### Q: What if my API has rate limits?
**A: Handle them in your code.** Implement proper rate limit handling in your `makeAPIRequest` method.
## 📚 Additional Resources
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [App2Chat Developer Documentation](https://docs.app2chat.ai/)
- [Marketplace Submission Guidelines](https://docs.app2chat.ai/marketplace/)
## 🆘 Support
- **Template Issues**: [Create an issue](https://github.com/app2chat/public-marketplace-mcp-template/issues)
- **Integration Help**: [App2Chat Documentation](https://docs.app2chat.ai/)
- **Marketplace Questions**: Contact App2Chat support team
## 📄 License
This template is provided under the MIT License. Your implementations can use any compatible license.
---
**Ready to build your MCP integration?** Start by customizing `src/mcp-server.js` and running `npm test` to validate compatibility! 🚀
