MetaCall MCP Server

A Model Context Protocol (MCP) server implemented in TypeScript on top of the metacall/protocol API. It exposes the complete MetaCall FaaS surface as MCP tools.

---

Architecture

┌────────────────────────────┐
│         MCP Client         │
│ (CLI / IDE / Local LLM)    │
└─────────────┬──────────────┘
              │ (JSON-RPC over stdio)
              ▼
┌────────────────────────────┐
│      MCP Server (TS)       │
│  - Tool Router             │
│  - Zod Validation          │
│  - Tool Handlers           │
│  - Error Boundary          │
└─────────────┬──────────────┘
              │ (Function Calls)
              ▼
┌────────────────────────────┐
│      Protocol Client       │
│  (metacall/protocol API)   │
└─────────────┬──────────────┘
              │ (Axios REST)
              ▼
┌────────────────────────────┐
│        MetaCall FaaS       │
│  (Deploy + Runtime Layer)  │
└────────────────────────────┘

---

Exposed Tools

System

Tool	Description
refresh	Refresh the MetaCall JWT authentication token
ready	Check if the server is ready
validate	Validate the current auth token
deployEnabled	Check if deployments are enabled

Subscriptions

Tool	Description
listSubscriptions	List all active subscriptions
listSubscriptionsDeploys	List deployments for subscriptions

Deployment

Tool	Description
inspect	Inspect all deployments
inspectByName	Inspect a deployment by name
upload	Upload a zip package/blob into the FaaS
add	Add a new deployment
deploy	Trigger a deployment
deployDelete	Delete a deployment
logs	Retrieve deployment logs

Repository

Tool	Description
branchList	List branches in the repository
fileList	List files in the repository

Invocation

Tool	Description
invoke	Invoke a deployed function
call	Call a function directly
await	Await an async function result

---

Design Principles

• 1:1 abstraction over the protocol API
• Async-safe Promise-based handlers
• Structured error boundary for consistent error handling
• Retry support via waitFor
• Zod-based input validation for all tool inputs
• Clean separation of concerns across layers

Installation & Setup

Prerequisites

• Node.js: v18 or higher.
• MetaCall Token: You need an active authentication token. You can get this by logging into dashboard.metacall.io.

---

1. Build the Server

First, clone this repository to your local machine, install the dependencies, and compile the TypeScript code:

git clone https://github.com/Somsubhra-Nandi/metacall-mcp-server.git
cd metacall-mcp-server
npm install
npm run build

Note: Get the absolute path of your metacall-mcp-server/dist/index.js file as we will need it for the client configuration.

---

2. Client Configuration

The Model Context Protocol (MCP) allows us to use this server across various AI clients. Below are the setup instructions for Claude Desktop and Google Antigravity.

---

Option A: Claude Desktop

1. Open your Claude Desktop configuration file based on your operating system:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MetaCall server to your mcpServers object. Replace the args path with the actual absolute path to dist/index.js, and insert your MetaCall token:

{
  "mcpServers": {
    "metacall-faas": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/metacall-mcp-server/dist/index.js"
      ],
      "env": {
        "METACALL_TOKEN": "your_jwt_token_here",
        "METACALL_BASE_URL": "https://dashboard.metacall.io"
      }
    }
  }
}

Windows Users: Remember to use double backslashes. e.g., C:\\Users\\Name\\metacall-mcp-server\\dist\\index.js

3. Restart Claude Desktop.

---

Option B: Google Antigravity

1. Open your Antigravity configuration file based on your operating system:

   • macOS / Linux: ~/.gemini/antigravity/mcp_config.json
   • Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json

2. Add the exact same JSON configuration block used for Claude Desktop (above) into your mcp_config.json file:

{
  "mcpServers": {
    "metacall-faas": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/metacall-mcp-server/dist/index.js"
      ],
      "env": {
        "METACALL_TOKEN": "your_jwt_token_here",
        "METACALL_BASE_URL": "https://dashboard.metacall.io"
      }
    }
  }
}

3. In the Antigravity UI, navigate to the Agent Manager panel, click Manage MCP Servers, and hit Refresh. The server will be connected.

Upload Tool – How to Provide the Zip Package

The upload tool sends a zip package to MetaCall Cloud before deploying it. The MetaCall API expects the package as a binary buffer. The zip file must be encoded as a base64 string and then reconstructed into a buffer inside the MCP server.

Base64 works across all MCP clients because it is simply a text representation of the binary zip file.

Two ways of providing the zip package are supported:

---

1. zipBase64 (Recommended and works for all)

This is the portable method and works with all MCP clients such as Claude, antigravity and others.

Steps

1. Create a zip file containing your source code. The source files should be at the root of the zip archive.

   Example structure:

   package.zip
   └── abc.js
   

2. Convert the zip file to a base64 string.

   Linux:

   base64 package.zip
   

   macOS:

   base64 package.zip
   

   Windows (PowerShell):

   [Convert]::ToBase64String([IO.File]::ReadAllBytes("absolute path of the zip file"))
   

3. Pass the base64 string to the upload tool.

   Example tool input:

   {
     "name": "myPackage",
     "zipBase64": "ABCDEF...",
     "runners": ["node"]
   }
   

The MCP server will convert the base64 string back into a binary buffer and send it to the MetaCall API.

---

2. zipPath (Local Development Only)

When the MCP server has direct access to the local filesystem (for example when testing locally or using tools like Antigravity), the zip file can be provided as a file path.

Example:

{
  "name": "myPackage",
  "zipPath": "./package.zip"
}

The MCP server reads the file from disk using the provided path and uploads it to MetaCall.

Note: zipPath may not work with remote LLM clients like Claude because those clients cannot access files on the MCP server's filesystem.

---

Recommendation

For compatibility across all MCP clients, using zipBase64 is recommended.