Skip to main content
Glama
itsanishjain

code-mode-alchemy-mcp

by itsanishjain
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

code-mode-alchemy-mcp

An MCP (Model Context Protocol) server that gives Claude access to Alchemy's blockchain APIs. Instead of defining 88+ individual tools, it loads all Alchemy API specs at startup and exposes just two tools — search and execute — keeping context usage minimal (~1,000 tokens vs. thousands).

Inspired by Cloudflare's Code Mode MCP pattern.

How It Works

At startup, the server fetches 10 Alchemy API specifications (6 REST OpenAPI + 4 JSON-RPC OpenRPC) and indexes all their endpoints. Claude can then:

  1. Search — find relevant endpoints by keyword

  2. Execute — run JavaScript code in a sandboxed environment against those endpoints

Claude → search("NFT owner") → finds getNFTsForOwner endpoint
Claude → execute(code)       → runs against Alchemy API, returns data

Loaded Specifications

REST (OpenAPI):

  • nft — NFT operations (mint, transfer, ownership queries)

  • portfolio — Wallet portfolio data

  • prices — Token pricing information

  • notify — Webhook notifications

  • transactions — Transaction history and details

  • accounts — Account management

JSON-RPC (OpenRPC):

  • transfers — Token transfer history (alchemy_getAssetTransfers)

  • token — Token metadata and balances (alchemy_getTokenBalances, etc.)

  • transaction-simulation — Simulate transactions before sending

  • bundler — ERC-4337 bundler operations

Related MCP server: Alchemy MCP Plugin

Prerequisites

Installation

git clone https://github.com/your-username/code-mode-alchemy-mcp
cd code-mode-alchemy-mcp
npm install
npm run build

Configuration

Copy the example environment file:

cp .env.example .env

Set your values in .env:

ALCHEMY_API_KEY=your_key_here
ALCHEMY_NETWORK=eth-mainnet

Supported Networks

Any network string Alchemy supports in their URL format, e.g.:

  • eth-mainnet

  • eth-sepolia

  • polygon-mainnet

  • arb-mainnet

  • opt-mainnet

  • base-mainnet

Add to Claude Desktop

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

{
  "mcpServers": {
    "alchemy": {
      "command": "node",
      "args": ["/absolute/path/to/code-mode-alchemy-mcp/dist/index.js"],
      "env": {
        "ALCHEMY_API_KEY": "your_key_here",
        "ALCHEMY_NETWORK": "eth-mainnet"
      }
    }
  }
}

Restart Claude Desktop. You should see the Alchemy MCP server connected.

Tools

search(query, limit?)

Searches across all loaded endpoint metadata (summaries, descriptions, paths, tags) and returns the most relevant endpoints.

Parameter

Type

Default

Description

query

string

required

Keywords to search for

limit

number

8

Max results to return (max 20)

Example queries:

  • "NFT owner" — find endpoints for fetching NFTs by owner

  • "token balance" — find token balance endpoints

  • "asset transfers" — find transfer history endpoints

  • "simulate transaction" — find simulation endpoints

execute(code)

Runs JavaScript code in a sandboxed Node.js VM with access to the Alchemy API. Execution is isolated with a 30-second timeout.

Available in the sandbox:

Name

Type

Description

request(url, params?, options?)

function

Simplified API caller. Replaces {apiKey} and {network} in the URL automatically.

fetch

function

Raw Fetch API for custom requests

ALCHEMY_API_KEY

string

Your API key

ALCHEMY_NETWORK

string

Your configured network

console.log

function

Output captured and returned

console.error

function

Errors captured and returned

REST example:

const data = await request(
  "https://{network}.g.alchemy.com/nft/v3/{apiKey}/getNFTsForOwner",
  { owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", withMetadata: true }
);
return data;

JSON-RPC example:

const data = await request(
  "https://{network}.g.alchemy.com/v2/{apiKey}",
  {
    jsonrpc: "2.0",
    method: "alchemy_getTokenBalances",
    params: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
    id: 1
  },
  { method: "POST" }
);
return data;

Usage Examples

NFTs for a wallet

"Show me all NFTs owned by 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Claude will:

  1. Call search("NFT owner") → finds getNFTsForOwner

  2. Call execute(...) → fetches and returns NFT data

Token balances

"What ERC-20 tokens does this address hold: 0x..."

Claude will:

  1. Call search("token balances") → finds alchemy_getTokenBalances

  2. Call execute(...) → returns token list with balances

Transaction history

"Show recent transactions for vitalik.eth"

Claude will:

  1. Call search("asset transfers") → finds alchemy_getAssetTransfers

  2. Call execute(...) → returns transfer history

Simulate a transaction

"What would happen if I sent 1 ETH from 0x... to 0x...?"

Claude will:

  1. Call search("simulate transaction") → finds simulation endpoint

  2. Call execute(...) → returns simulation result

Development

# Run in development mode (no build step needed)
npm run dev

# Build for production
npm run build

# Run the compiled server
npm start

Project Structure

code-mode-alchemy-mcp/
├── src/
│   └── index.ts        # Everything: spec loading, search, sandbox, MCP server
├── dist/
│   ├── index.js        # Compiled output (run this)
│   └── index.d.ts      # TypeScript declarations
├── .env.example        # Environment variable template
├── package.json
└── tsconfig.json

Architecture

Claude Desktop
     │
     │  MCP (stdio)
     ▼
MCP Server
     │
     ├── Startup: fetch 10 specs → index all endpoints
     │
     ├── search(query)
     │     └── score & rank endpoints by keyword match
     │
     └── execute(code)
           └── vm.runInNewContext() with 30s timeout
                 └── request() helper → Alchemy REST/RPC APIs

Why two tools instead of 88+?

Defining every Alchemy endpoint as a separate MCP tool would consume thousands of tokens just in tool definitions, before Claude even starts reasoning. This pattern loads specs once, searches them dynamically, and executes code — using ~1,000 tokens of tool definitions regardless of how many endpoints Alchemy adds.

Security Notes

  • Code in execute() runs in a Node.js vm sandbox with no access to the filesystem, environment, or require

  • The API key is injected by the sandbox via placeholder replacement — it is never returned in search results or exposed to user-visible output

  • Execution is limited to 30 seconds to prevent runaway code

References

License

MIT

Available Tools

2 tools
executeA

Execute JavaScript code against Alchemy's APIs. The sandbox provides:

  • request(url, params?, options?) — GET/REST endpoint; {apiKey} and {network} in URLs are auto-replaced

  • fetch — raw fetch for custom requests (use for JSON-RPC POST calls)

  • ALCHEMY_API_KEY — the configured API key string

  • ALCHEMY_NETWORK — current network (default: eth-mainnet)

  • console.log() — captured and returned in logs

REST example:

const data = await request(
  "https://{network}.g.alchemy.com/nft/v3/{apiKey}/getNFTsForOwner",
  { owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", withMetadata: false }
);
return data;

JSON-RPC example:

const res = await fetch(
  `https://{network}.g.alchemy.com/v2/${ALCHEMY_API_KEY}`.replace("{network}", ALCHEMY_NETWORK),
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "alchemy_getTokenBalances", params: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"] })
  }
);
return await res.json();
ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesJavaScript code to execute. Use return to send back results.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full disclosure burden. It does valuable work by documenting sandbox globals, auto-substitution of {apiKey}/{network}, and that console.log is captured. However, for arbitrary code execution it omits critical traits: whether mutating requests are possible/permitted, execution timeouts, rate limits, and error behavior. These gaps matter for a tool that can issue arbitrary network calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then a tight bulleted inventory of sandbox capabilities, then two minimal-but-complete examples. The length is earned: each example teaches a distinct calling convention (REST via request vs JSON-RPC via fetch), and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must explain results, and it does: `return` sends back data and console.log is captured in logs. Combined with the runnable examples this is close to complete, though timeout/error semantics and any permission boundaries remain unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is a single parameter, so the baseline is 3. The description adds real value beyond the schema by demonstrating via two complete code samples how the `code` string is structured and how `return` propagates results, which clarifies the contract more concretely than the schema's one-liner.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb (execute) and resource (JavaScript code against Alchemy's APIs) and immediately delineates the sandbox surface. The purpose is unambiguous, but the description never acknowledges or differentiates from the sibling `search` tool, so it falls short of the 5 threshold which requires sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is implied rather than stated: the contrast between `request` (GET/REST) and `fetch` (raw, use for JSON-RPC POST) tells the agent how to use primitives within the sandbox, but nothing says when to reach for `execute` over `search`. The escape-hatch nature is inferable but never explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedexecute
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 2 tools

Disambiguation5/5

Search and execute have clearly distinct roles: search discovers API endpoints, while execute runs arbitrary JavaScript against them. There is no overlap in purpose, and the descriptions explicitly guide sequential use.

Naming Consistency5/5

Both tool names are concise, lowercase imperative verbs following the same bare-verb convention. No inconsistent casing or mixed noun/verb patterns.

Tool Count4/5

Two tools is slightly below the typical 3-15 range, but both are essential and earn their place: one for discovery and one for universal execution. The set is minimal rather than redundant.

Completeness4/5

Search plus execute covers endpoint discovery and arbitrary REST/JSON-RPC calls, which is nearly complete for a code-mode API gateway. Minor gaps remain, such as no structured endpoint-schema lookup or built-in pagination helpers, but agents can work around these.

Resources

Related MCP Connectors

Related MCP Servers