- Node.js >= 18 (for running MCP server and SAK tooling)
- Rust >= 1.70 (optional, for compiling custom Solana MPC components)
- Solana CLI installed and configured for your devnet or mainnet cluster
- Yarn or npm (package managers)
- Docker (optional but helpful for spinning up dependencies like Redis or Postgres)
Tool versions used in this guide:
| Tool |
Version |
| Solana CLI |
1.14.10 |
| Solana Agent Kit |
v0.4.2 |
| MCP Server (Node) |
v0.7.5 |
| Solana MCP Claude |
v0.1.0 (alpha) |
Packages are actively evolving, so always check the latest on GitHub or npm.
Note: Many MCP and agent suites are in early development, so expect some rough edges.
Setting Up a Solana MCP Server
The core MCP server acts as a context provider for your AI agents, querying and caching blockchain data efficiently.
Installation
## Clone the MCP server repo (NodeJS version)
git clone https://github.com/mcp-protocol/mcp-node-server.git
cd mcp-node-server
## Install dependencies
yarn install
## Build
npx tsc
Configuration
Create a .env file with the following minimal settings:
## .env
RPC_URL=https://api.devnet.solana.com
REDIS_URL=redis://localhost:6379
CACHE_TTL=60
## Optional
LOG_LEVEL=info
RPC_URL points to your Solana cluster RPC. Devnet is perfect for testing.
Start the server
yarn start
You should see logs about successful startup and cache initialization. The server exposes a REST API on port 8080 by default.
Tip: Running Redis locally helps performance when multiple agents hit the server.
Server API Leak Example
Query the status endpoint:
curl http://localhost:8080/status
Expected output:
{
"status": "ok",
"rpc": "https://api.devnet.solana.com"
}
You now have a working MCP server hooked to Solana devnet.
For a deeper dive, refer to the general setup at base MCP server setup.
Configuring the Solana Agent Kit for MCP
The Solana Agent Kit (SAK) simplifies spawning on-chain AI agents that consume MCP context.
Installation
npm install --save @solana/agent-kit
Basic Usage Example
Here's how to configure SAK to point to your MCP server:
import { Agent } from '@solana/agent-kit';
const agent = new Agent({
mcpServerUrl: 'http://localhost:8080',
solanaRpcUrl: 'https://api.devnet.solana.com',
network: 'devnet',
});
await agent.initialize();
console.log('Agent ready', agent.address);
This snippet sets up your agent to pull context from the MCP server.
Key Management
SAK defaults to a software wallet-derived private key for dev/testing. In production, use hardware wallets or key management services, because agent wallets can be drained if exposed.
You can also pass explicit session keys with spending limits;
const sessionKey = {
pubkey: '...',
spendingLimit: 0.1, // SOL
expiry: Date.now() + 3600000 // 1 hour
};
agent.addSessionKey(sessionKey);
Session keys allow scoped, temporary permissions for agent interactions.
Integrating Solana MCP Claude for AI Agents
Solana MCP Claude provides an AI inference layer specifically tuned for Solana agent workflows.
You’ll want to install the client SDK:
npm install --save @solana/mcp-claude
Example Integration
import { ClaudeClient } from '@solana/mcp-claude';
const claude = new ClaudeClient({
serverUrl: 'http://localhost:8080',
model: 'solana-mcp-claude-v0',
});
const prompt = 'Fetch SPL token balances for wallet XYZ';
const response = await claude.generate({ prompt });
console.log('AI Response:', response.text);
The model currently runs inference via the MCP server proxy, querying on-chain data and returning context-sensitive answers.
Alpha Caveats
The Claude integration is experimental — expect longer latencies and occasional failures. Monitor logs closely.
On-Chain Data Integration for AI Agents
MCP servers can pull on-chain data from Solana through RPC or indexer backends.
Example: Fetching Token Balances
Under the hood, MCP server scripts query SPL token accounts:
async function getTokenBalances(wallet: string) {
const accounts = await connection.getParsedTokenAccountsByOwner(
new PublicKey(wallet),
{ programId: TOKEN_PROGRAM_ID }
);
return accounts.value.map(acc => ({
mint: acc.account.data.parsed.info.mint,
amount: acc.account.data.parsed.info.tokenAmount.uiAmount,
}));
}
MCP caches these results to avoid repeated expensive RPC calls.
Expanding with DeFi Data
You can plug DeFi aggregator APIs like Jupiter into MCP server ingestion pipelines for real-time swap data, useful for DeFAI agents.
Check mcp-server-tools-comparison for notes on available indexers and savings.
Security Considerations and Best Practices
Here are a few things I learned the hard way when wiring up agent wallets:
- Never store private keys or seed phrases in plaintext or inside your MCP server environment. Encrypt and restrict filesystem permissions.
- Use session keys with spending limits to minimize damage potential. If a session key leaks, losses are capped.
- Audit all smart contract interactions your agent triggers. Watch for unsafe patterns like unlimited approvals.
- Harden MCP server access with authentication, or host it in a trusted VPC. If attackers control your MCP server, they can feed malicious context.
- Prefer testnet or devnet deployments during development to reduce risk of mainnet asset loss.
For a security checklist, mcp-server-security-best-practices is a solid companion.
Troubleshooting Common Issues
MCP Server Not Starting
- Check your
.env for correct RPC and Redis URLs.
- Run Redis locally or adjust
REDIS_URL.
- Confirm Node version compatibility.
Agent Fails to Connect to MCP
- Verify your
mcpServerUrl matches the MCP server endpoint.
- Check CORS settings on MCP server if calling from browsers.
Slow Response or Timeouts
- Inspect Redis cache hits vs misses.
- Increase cache TTL if data freshness allows.
Claude Model Returns Errors
- Confirm correct model string (like
solana-mcp-claude-v0).
- Check MCP server logs — model infrastructure may be down or resource constrained.
See mcp-server-troubleshooting for additional examples.
Summary and Next Steps
You’ve now got a baseline Solana MCP server running, connected your Solana Agent Kit to it, and experimented with the Solana MCP Claude AI model. This trio opens doors to powerful AI agents that understand on-chain Solana context in real-time.
Next, I’d recommend:
- Extending MCP server ingestion pipelines with custom Solana program data.
- Adding advanced payment protocols for secure agent payout flows via mcp-agent-payment-protocols.
- Hardening your deployment using mcp-server-security-best-practices.
The tools and frameworks here are young but evolving fast—staying hands-on is the best way to catch all the nuances.
Good luck shipping your Solana AI agents!
For foundational MCP concepts and multi-chain comparisons, check out what is MCP and evm MCP server overview.
