SurfRank MCP Server

list_projects

List all SurfRank projects the caller has access to. Returns every tracked website associated with your account or a single project if API key is scoped.

Instructions

List every SurfRank project (tracked website) the caller has access to. If the API key is scoped to a single project, only that one is returned.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/tools/projects.js:8-15 (handler)

The handler function for the 'list_projects' tool. It is an async function that calls api.get('/projects') to retrieve all SurfRank projects.

{
  name: 'list_projects',
  description:
    'List every SurfRank project (tracked website) the caller has access to. ' +
    'If the API key is scoped to a single project, only that one is returned.',
  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
  handler: async () => api.get('/projects'),
},

src/tools/projects.js:7-15 (schema)

The input schema definition for 'list_projects'. It has no required parameters and accepts an empty object (type: object, no properties, additionalProperties: false).

export const projectTools = [
  {
    name: 'list_projects',
    description:
      'List every SurfRank project (tracked website) the caller has access to. ' +
      'If the API key is scoped to a single project, only that one is returned.',
    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
    handler: async () => api.get('/projects'),
  },

src/index.js:31-39 (registration)
The 'list_projects' tool is registered as part of the projectTools array, which is spread into ALL_TOOLS (line 32) and served via the MCP ListToolsRequestSchema handler (line 58). The tool is also looked up by name in the toolByName Map (line 41) for execution via CallToolRequestSchema (line 69).
```
const ALL_TOOLS = [
  ...projectTools,
  ...keywordTools,
  ...reportTools,
  ...quickTestTools,
  ...keywordResearchTools,
  ...competitorTools,
  ...opportunityTools,
];
```
src/tools/projects.js:1-1 (helper)
The api client used by the handler is imported from '../client.js', which provides the get/post/patch/delete methods that call the SurfRank public API.
```
import { api } from '../client.js';
```
src/tools/projects.js:9-9 (registration)
The tool is named 'list_projects' as part of the projectTools array exported from this file.
```
name: 'list_projects',
```

Tool Definition Quality

A4.5/5.0

Behavior4/5

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

With no annotations, the description discloses the key behavior that results depend on API key scope. This is sufficient for a simple listing tool, though it omits potential details like sorting or limits.

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?

Two concise sentences, front-loaded with the main purpose and a specific behavioral note. No wasted words.

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

Completeness5/5

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

Given the tool's simplicity (no parameters, no output schema, no annotations), the description is fully complete, covering both normal behavior and scoped key behavior.

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?

The input schema has no parameters, so the description does not need to add parameter info. Baseline for 0 parameters is 4.

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

Purpose5/5

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

The description clearly states the verb 'list' and the resource 'SurfRank project (tracked website)', distinguishing it from sibling tools like get_project (single project) and create_project. It also adds the scoping behavior.

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

Usage Guidelines4/5

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

The description implies when to use: to list all accessible projects. It mentions scoping nuance but does not explicitly state when not to use or alternatives, though siblings like get_project serve different needs.

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

Install Server

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SurfRankAI/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server