Moralis MCP Server

Instructions

Implementation Reference

• src/utils/execute-api-tool.ts:34-252 (handler)

  The `executeApiTool` function serves as the primary handler for all API-based tools, including `evm_getmultiplenfts`. It validates user arguments against the tool's input schema, constructs the HTTP request to the Moralis API using the tool definition's path, method, parameters, and security requirements, executes the request with Axios, and returns a formatted text response containing the API result.
  export async function executeApiTool( toolName: string, definition: McpToolDefinition, toolArgs: JsonObject, allSecuritySchemes: Record<string, any>, token?: string, ): Promise<CallToolResult> { try { // Validate arguments against the input schema let validatedArgs: JsonObject; try { const zodSchema = getZodSchemaFromJsonSchema( definition.inputSchema, toolName, ); const argsToParse = typeof toolArgs === 'object' && toolArgs !== null ? toolArgs : {}; validatedArgs = zodSchema.parse(argsToParse); } catch (error: unknown) { if (error instanceof ZodError) { const validationErrorMessage = `Invalid arguments for tool '${toolName}': ${error.errors.map((e) => `${e.path.join('.')} (${e.code}): ${e.message}`).join(', ')}`; return { content: [{ type: 'text', text: validationErrorMessage }] }; } else { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: 'text', text: `Internal error during validation setup: ${errorMessage}`, }, ], }; } } // Prepare URL, query parameters, headers, and request body let urlPath = definition.pathTemplate; const queryParams: Record<string, any> = {}; const headers: Record<string, string> = { Accept: 'application/json', 'X-Moralis-Platform': 'MCP', }; let requestBodyData: any = undefined; // Apply parameters to the URL path, query, or headers definition.executionParameters.forEach((param) => { const value = validatedArgs[param.name]; if (typeof value !== 'undefined' && value !== null) { if (param.in === 'path') { urlPath = urlPath.replace( `{${param.name}}`, encodeURIComponent(String(value)), ); } else if (param.in === 'query') { queryParams[param.name] = value; } else if (param.in === 'header') { headers[param.name.toLowerCase()] = String(value); } } }); // Ensure all path parameters are resolved if (urlPath.includes('{')) { throw new Error(`Failed to resolve path parameters: ${urlPath}`); } // Construct the full URL const requestUrl = `${definition.baseUrl}${urlPath}`; // Handle request body if needed if ( definition.requestBodyContentType && typeof validatedArgs['requestBody'] !== 'undefined' ) { requestBodyData = validatedArgs['requestBody']; headers['content-type'] = definition.requestBodyContentType; } // Apply security requirements if available // Security requirements use OR between array items and AND within each object const appliedSecurity = definition.securityRequirements?.find((req) => { // Try each security requirement (combined with OR) return Object.entries(req).every(([schemeName, scopesArray]) => { const scheme = allSecuritySchemes[schemeName]; if (!scheme) return false; // API Key security (header, query, cookie) if (scheme.type === 'apiKey') { return !!token || !!Config.MORALIS_API_KEY; } return false; }); }); // If we found matching security scheme(s), apply them if (appliedSecurity) { // Apply each security scheme from this requirement (combined with AND) for (const [schemeName, scopesArray] of Object.entries(appliedSecurity)) { const scheme = allSecuritySchemes[schemeName]; // API Key security if (scheme?.type === 'apiKey') { const apiKey = token || Config.MORALIS_API_KEY; if (apiKey) { if (scheme.in === 'header') { headers[scheme.name.toLowerCase()] = apiKey; console.error( `Applied API key '${schemeName}' in header '${scheme.name}'`, ); } } } } } // Log warning if security is required but not available else if (definition.securityRequirements?.length > 0) { // First generate a more readable representation of the security requirements const securityRequirementsString = definition.securityRequirements .map((req) => { const parts = Object.entries(req) .map(([name, scopesArray]) => { const scopes = scopesArray as string[]; if (scopes.length === 0) return name; return `${name} (scopes: ${scopes.join(', ')})`; }) .join(' AND '); return `[${parts}]`; }) .join(' OR '); console.warn( `Tool '${toolName}' requires security: ${securityRequirementsString}, but no suitable credentials found.`, ); } // Prepare the axios request configuration const config: AxiosRequestConfig = { method: definition.method.toUpperCase(), url: requestUrl, params: queryParams, headers: headers, ...(requestBodyData !== undefined && { data: requestBodyData }), }; // Log request info to stderr (doesn't affect MCP output) console.error( `Executing tool "${toolName}": ${config.method} ${config.url}`, ); // Execute the request const response = await axios(config); // Process and format the response let responseText = ''; const contentType = response.headers['content-type']?.toLowerCase() || ''; // Handle JSON responses if ( contentType.includes('application/json') && typeof response.data === 'object' && response.data !== null ) { try { responseText = JSON.stringify(response.data, null, 2); } catch (e) { responseText = '[Stringify Error]'; } } // Handle string responses else if (typeof response.data === 'string') { responseText = response.data; } // Handle other response types else if (response.data !== undefined && response.data !== null) { responseText = String(response.data); } // Handle empty responses else { responseText = `(Status: ${response.status} - No body content)`; } // Return formatted response return { content: [ { type: 'text', text: `API Response (Status: ${response.status}):\n${responseText}`, }, ], }; } catch (error: unknown) { // Handle errors during execution let errorMessage: string; // Format Axios errors specially if (axios.isAxiosError(error)) { errorMessage = formatApiError(error); } // Handle standard errors else if (error instanceof Error) { errorMessage = error.message; } // Handle unexpected error types else { errorMessage = `Unexpected error: ${String(error)}`; } // Log error to stderr console.error( `Error during execution of tool '${toolName}':`, errorMessage, ); // Return error message to client return { content: [{ type: 'text', text: errorMessage }] }; } }
• src/server.ts:96-120 (registration)

  MCP server registration of the generic tool call handler. Looks up the tool definition by prefixed name (e.g., 'evm_getmultiplenfts') in the toolDefinitionMap and dispatches to `executeApiTool`.
  server.setRequestHandler( CallToolRequestSchema, async (request: CallToolRequest, c): Promise<CallToolResult> => { const { name: toolName, arguments: toolArgs } = request.params; const toolDefinition = toolDefinitionMap[toolName]; if (!toolDefinition) { console.error(`Error: Unknown tool requested: ${toolName}`); return { content: [ { type: 'text', text: `Error: Unknown tool requested: ${toolName}`, }, ], }; } return executeApiTool( toolName, toolDefinition, toolArgs ?? {}, securitySchemes, c.authInfo?.token, ); }, );
• src/server.ts:26-44 (registration)

  Dynamic registration of tools from OpenAPI spec. Fetches and parses the Moralis EVM spec, extracts tools with 'evm_' prefix using `extractToolsFromApi`, filters blacklist, and builds `toolDefinitionMap` keyed by prefixed tool names like 'evm_getmultiplenfts'.
  async function mapToolDefinitions(config: SchemaConfig) { const spec = (await getSpec(config.specUrl)) as OpenAPIV3DocumentX; const api = (await SwaggerParser.dereference(spec)) as OpenAPIV3DocumentX; const tools = extractToolsFromApi(api, config.prefix); const blacklist = Array.isArray(api['x-mcp-blacklist']) ? api['x-mcp-blacklist'].map((e) => `${config.prefix}${e.toLowerCase()}`) : []; const toolDefinitionMap: Record<string, McpToolDefinition> = {}; for (const tool of tools) { if (blacklist.includes(tool.name)) continue; toolDefinitionMap[tool.name] = { ...tool, baseUrl: config.baseUrl, }; } return toolDefinitionMap; }
• src/parser/extract-tools.ts:17-93 (helper)

  Helper that extracts tool definitions from OpenAPI spec paths/operations, generates prefixed names (e.g., 'evm_getmultiplenfts' from operationId or path), generates input schemas, and prepares execution details.
  export function extractToolsFromApi( api: OpenAPIV3DocumentX, prefix?: string ): McpToolDefinition[] { const tools: McpToolDefinition[] = []; const usedNames = new Set<string>(); const globalSecurity = api.security || []; if (!api.paths) return tools; for (const [path, pathItem] of Object.entries(api.paths)) { if (!pathItem) continue; for (const method of Object.values(OpenAPIV3.HttpMethods)) { const operation = pathItem[method]; if (!operation) continue; // Generate a unique name for the tool let baseName = operation.operationId || generateOperationId(method, path); if (!baseName) continue; // Sanitize the name to be MCP-compatible (only a-z, 0-9, _, -) baseName = baseName .replace(/\./g, '_') .replace(/[^a-z0-9_-]/gi, '_') .toLowerCase(); let finalToolName = baseName; let counter = 1; while (usedNames.has(finalToolName)) { finalToolName = `${baseName}_${counter++}`; } usedNames.add(finalToolName); // Get or create a description const description = operation.description || operation.summary || `Executes ${method.toUpperCase()} ${path}`; const prompt = operation['x-mcp-prompt']; // Generate input schema and extract parameters const { inputSchema, parameters, requestBodyContentType } = generateInputSchemaAndDetails(operation); // Extract parameter details for execution const executionParameters = parameters.map((p) => ({ name: p.name, in: p.in, })); // Determine security requirements const securityRequirements = operation.security === null ? globalSecurity : operation.security || globalSecurity; // Create the tool definition tools.push({ name: prefix + finalToolName, description, inputSchema, method, pathTemplate: path, parameters, executionParameters, requestBodyContentType, securityRequirements, operationId: baseName, prompt, }); } } return tools; }
• src/parser/extract-tools.ts:95-180 (schema)

  Generates the input schema for each tool from OpenAPI operation parameters and requestBody. This schema is used for MCP tool definition and runtime validation in `executeApiTool`.
  /** * Generates input schema and extracts parameter details from an operation * * @param operation OpenAPI operation object * @returns Input schema, parameters, and request body content type */ export function generateInputSchemaAndDetails( operation: OpenAPIV3.OperationObject, ): { inputSchema: JSONSchema7 | boolean; parameters: OpenAPIV3.ParameterObject[]; requestBodyContentType?: string; } { const properties: { [key: string]: JSONSchema7 | boolean } = {}; const required: string[] = []; // Process parameters const allParameters: OpenAPIV3.ParameterObject[] = Array.isArray( operation.parameters, ) ? operation.parameters.map((p) => p as OpenAPIV3.ParameterObject) : []; allParameters.forEach((param) => { if (!param.name || !param.schema) return; const paramSchema = mapOpenApiSchemaToJsonSchema( param.schema as OpenAPIV3.SchemaObject, ); if (typeof paramSchema === 'object') { paramSchema.description = param.description || paramSchema.description; } properties[param.name] = paramSchema; if (param.required) required.push(param.name); }); // Process request body (if present) let requestBodyContentType: string | undefined = undefined; if (operation.requestBody) { const opRequestBody = operation.requestBody as OpenAPIV3.RequestBodyObject; const jsonContent = opRequestBody.content?.['application/json']; const firstContent = opRequestBody.content ? Object.entries(opRequestBody.content)[0] : undefined; if (jsonContent?.schema) { requestBodyContentType = 'application/json'; const bodySchema = mapOpenApiSchemaToJsonSchema( jsonContent.schema as OpenAPIV3.SchemaObject, ); if (typeof bodySchema === 'object') { bodySchema.description = opRequestBody.description || bodySchema.description || 'The JSON request body.'; } properties['requestBody'] = bodySchema; if (opRequestBody.required) required.push('requestBody'); } else if (firstContent) { const [contentType] = firstContent; requestBodyContentType = contentType; properties['requestBody'] = { type: 'string', description: opRequestBody.description || `Request body (content type: ${contentType})`, }; if (opRequestBody.required) required.push('requestBody'); } } // Combine everything into a JSON Schema const inputSchema: JSONSchema7 = { type: 'object', properties, ...(required.length > 0 && { required }), }; return { inputSchema, parameters: allParameters, requestBodyContentType }; }
• src/config.ts:15-22 (helper)

  EVM configuration defining the 'evm_' prefix for tool names, Moralis API base URL, and OpenAPI spec URL from which `evm_getmultiplenfts` is extracted.
  evm: { prefix: 'evm_', baseUrl: process.env.API_BASE_URL || 'https://deep-index.moralis.io/api/v2.2', specUrl: process.env.API_SPEC_URL || 'https://deep-index.moralis.io/api-docs-2.2/v2.2/swagger.json', },