iwy.ai MCP Server

⚠️ *Beta Pre-Release - This is an early version. API may change.

Model Context Protocol (MCP) server for iwy.ai - enables Claude to create and manage AI agents and tool integrations through the iwy.ai API.

Features

• Complete Agent Management: Create, read, update, and delete AI conversational agents
• Tool Integration: Manage webhook-based tools for agent capabilities
• Testing Support: Test tools before deploying to production agents
• Comprehensive Documentation: Built-in API reference and configuration guides
• Type Safety: Full TypeScript support with Zod validation
• Robust Error Handling: Automatic retries and detailed error messages

Installation

Global Installation (Recommended)

npm install -g @iwy/mcp

Local Installation

npm install @iwy/mcp

Configuration

1. Get Your API Key

1. Visit app.iwy.ai/settings
2. Generate a new API key
3. Save it securely

2. Configure Claude

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "iwy": {
      "command": "npx",
      "args": ["-y", "@iwy/mcp"],
      "env": {
        "IWY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

Installation Steps:

1. Install the package globally:

npm install -g @iwy/mcp

2. Use jq to add the server to ~/.claude.json:

jq '.mcpServers["iwy"] = {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@iwy/mcp"],
  "env": {
    "IWY_API_KEY": "your_api_key_here"
  }
}' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json

Or manually edit ~/.claude.json and add to the mcpServers object:

{
  "mcpServers": {
    "iwy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@iwy/mcp"],
      "env": {
        "IWY_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Restart Claude Code to load the MCP server.

Testing:

# List your agents
"List my iwy.ai agents"

# Get agent details
"Show me details for agent <agent_id>"

# Create a new agent
"Create an iwy.ai customer service agent"

3. Environment Variable

Alternatively, set the API key as an environment variable:

export IWY_API_KEY="your_api_key_here"

Known Issues

API Endpoint Version (Current Package)

The current npm package version may use the wrong API endpoint (https://api.iwy.ai instead of https://api.iwy.ai/v1). This has been identified and will be fixed in the next release.

Temporary Workaround (if you encounter "Resource not found" errors):

Find your global npm packages location and update the API client:

# Find the installation path
NPM_PATH=$(npm root -g)/@iwy/mcp/dist/client.js

# Update the baseURL
sed -i "s|baseURL: 'https://api.iwy.ai'|baseURL: 'https://api.iwy.ai/v1'|" "$NPM_PATH"

This will be resolved in version 0.2.2+.

Available Tools

Agent Management (5 tools)

| Tool | Description | |------|-------------| | list_iwy_agents | List all agents in your account | | get_iwy_agent | Get detailed agent configuration | | create_iwy_agent | Create a new AI agent | | update_iwy_agent | Update existing agent | | delete_iwy_agent | Delete an agent |

Tool Management (6 tools)

| Tool | Description | |------|-------------| | list_iwy_tools | List all webhook tools | | get_iwy_tool | Get detailed tool configuration | | create_iwy_tool | Create a new tool integration | | update_iwy_tool | Update existing tool | | delete_iwy_tool | Delete a tool | | test_iwy_tool | Test tool execution |

Usage Examples

Creating a Customer Service Agent

User: Create a customer service agent for my e-commerce store

Claude: I'll create an iwy.ai agent for customer service.

[Creates agent with appropriate configuration]

✅ Created agent with ID: 550e8400-e29b-41d4-a716-446655440000

Adding a Weather Tool

User: Add a weather lookup tool

Claude: I'll create a tool integration for weather lookup.

[Creates tool with webhook configuration]

✅ Created tool with ID: dcfae097-1b37-4444-bb0c-1a6abb0320fd

Testing a Tool

User: Test the weather tool with "San Francisco"

Claude: [Tests tool with parameters]

✅ Test successful!
- Execution time: 245ms
- Response: {"temperature": 68, "conditions": "sunny"}

Documentation Resources

The server provides three built-in documentation resources accessible through Claude:

• iwy://docs/agents - Agent API reference
• iwy://docs/tools - Tool API reference
• iwy://docs/configuration - Setup and configuration guide

Development

Building from Source

git clone https://github.com/iwy-ai/mcp.git
cd mcp
npm install
npm run build

Running Locally

export IWY_API_KEY="your_api_key_here"
node dist/index.js

Architecture

src/
├── index.ts              # MCP server entry point
├── client.ts             # iwy.ai API client
├── types.ts              # TypeScript type definitions
├── schemas/
│   ├── agent.ts          # Agent validation schemas
│   └── tool.ts           # Tool validation schemas
├── tools/
│   ├── agents.ts         # Agent tool handlers
│   └── tools.ts          # Tool tool handlers
├── utils/
│   ├── errors.ts         # Error handling
│   └── validation.ts     # Input validation
└── resources/
    ├── agent-docs.md     # Agent documentation
    ├── tool-docs.md      # Tool documentation
    └── config-guide.md   # Configuration guide

Error Handling

The server provides detailed error messages with suggestions:

| Error Code | Description | Suggestion | |------------|-------------|------------| | UNAUTHORIZED | Invalid API key | Check IWY_API_KEY configuration | | NOT_FOUND | Resource doesn't exist | Use list operation to find valid IDs | | INVALID_REQUEST | Validation failed | Check required fields and types | | SERVER_ERROR | iwy.ai API error | Automatic retry, contact support if persists | | TIMEOUT | Request timeout | Increase timeout or retry |

Requirements

• Node.js >= 18.0.0
• iwy.ai API key from app.iwy.ai/settings

License

MIT License - see LICENSE file for details

Links

• iwy.ai Website
• iwy.ai Documentation
• API Reference
• Changelog
• MCP Specification
• GitHub Repository
• Report Issues

Support

For issues, questions, or feature requests:

• Open a GitHub issue
• Check the documentation
• Contact iwy.ai support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request