Documentation

Everything you need to install, configure, and use the Altab intelligence layer. One MCP server, nine tools, any AI coding agent.

Quick Start

Add the Altab MCP server to your AI coding tool. Setup takes less than 30 seconds.

claude mcp add altab --transport http https://api.altab.ai/mcp

codex mcp add altab --url https://api.altab.ai/mcp

{
  "mcpServers": {
    "altab": {
      "url": "https://api.altab.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "altab": {
      "url": "https://api.altab.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "altab": {
      "url": "https://api.altab.ai/mcp"
    }
  }
}

{
  "servers": {
    "altab": {
      "type": "http",
      "url": "https://api.altab.ai/mcp"
    }
  }
}

Authentication

No API keys to manage. You sign in through your browser on the first tool call, and your MCP client handles the rest.

How it works

1. Your AI tool calls an Altab tool for the first time (e.g. search_codebase)
2. Your browser opens and asks you to sign in with GitHub, Google, or email
3. You authorize Altab and your browser redirects back
4. All subsequent tool calls are authenticated automatically

Sessions refresh automatically. If you go a long time without using Altab, you may need to sign in again.

Revoking access

Remove the MCP server from your client configuration. If you signed in with GitHub, you can also revoke from Settings > Applications > Authorized OAuth Apps.

First Query

After installing, just talk to your AI agent normally. Include a repo_url so Altab knows which project to work with.

Example prompts

"Use Altab to search for authentication middleware in github.com/acme/backend"

"What functions call handle_payment? Check using Altab on github.com/acme/backend"

"Before I refactor the User class, show me the blast radius using Altab"

What happens on first use

1. Altab checks if this project has been indexed. If yes, the tool runs immediately
2. If not yet indexed, Altab begins indexing automatically. Typically 2-5 minutes
3. Check progress anytime with brain_status
4. Once indexing completes, all 9 tools are available. Future sessions start instantly

Response format

Altab returns plain text your AI agent can read and reason about. Search results include file paths, line numbers, and code snippets. Brain tools return symbols, call chains, and relationships.

Search Tools

Three tools for finding code. Altab goes beyond simple text matching. It understands what your code means and how it's structured.

Brain Tools

Six tools for deep structural understanding. The project brain maps every function, class, method, and module and understands how they relate.

Plans & Limits

Every tool call counts as one query. Daily limits reset at midnight UTC. Check remaining queries with brain_status.

What counts as a query?

Each individual tool call counts as one query. If your AI agent calls search_codebase and then brain_callers, that's 2 queries. Authentication and token refresh don't count.

Free tier

The free plan gives you the full intelligence layer with 1 project and 50 queries per day. Enough to evaluate the platform. Upgrade for unlimited projects and higher limits.

Core Concepts

Repository URL

Tools accept a repo_url parameter. Use the format github.com/owner/repo. Altab normalizes automatically. All of these are equivalent:

• github.com/acme/backend
• https://github.com/acme/backend
• https://github.com/acme/backend.git

Session Binding

After the first call with a repo_url, that project is bound to your session. All subsequent calls use it automatically. Sessions last 1 hour. To switch, provide a different repo_url.

Auto-Indexing

When you reference a new project, Altab indexes it automatically. No manual setup. Typically 2-5 minutes.

Incremental Updates

After the initial index, only changed files are re-processed when you push. Your AI agent always has the latest state.

Privacy & Security

Each user's data is fully isolated. No other user can access your project data. Altab does not use your code for training.

Best Practices

Altab works out of the box, but a short config snippet tells your AI agent to consistently prefer Altab over basic text search.

Recommended workflow

1. Call brain_status to verify the index is ready
2. Use search_codebase to discover relevant code
3. Use brain_symbol_lookup, brain_callers, or brain_callees for deep analysis
4. Call brain_conventions before writing new code
5. Call brain_blast_radius before changing existing code

Project configuration

Add one of these snippets so your AI agent consistently uses Altab tools.

## Altab Intelligence Layer

When Altab MCP tools are available, ALWAYS prefer them over built-in alternatives:

- **Code search:** Use `search_codebase` instead of Grep or file search
- **Find definitions:** Use `search_definitions` instead of grep for def/class/function
- **Find usages:** Use `search_usages` instead of grep for symbol names
- **Understand symbols:** Use `brain_symbol_lookup` for type, signature, and relationships
- **Trace callers/callees:** Use `brain_callers` / `brain_callees` instead of manually reading files
- **Before modifying code:** ALWAYS call `brain_blast_radius` to understand impact
- **Before writing new code:** ALWAYS call `brain_conventions` to match project patterns

When Altab MCP tools are available, always use them for code search and analysis:

- Use search_codebase instead of @codebase or built-in search
- Use search_definitions instead of go-to-definition
- Use search_usages instead of grep for symbol references
- Use brain_symbol_lookup to understand any symbol deeply
- Use brain_callers / brain_callees to trace call chains
- Always call brain_blast_radius before modifying existing code
- Always call brain_conventions before generating new code

## Altab Intelligence Layer

When Altab MCP tools are available, prefer them over built-in alternatives:

- Use search_codebase instead of grep or file search
- Use search_definitions instead of grep for def/class/function
- Use search_usages instead of grep for symbol names
- Use brain_symbol_lookup for type, signature, and relationships
- Use brain_callers / brain_callees instead of manually reading files
- Call brain_blast_radius before modifying any existing code
- Call brain_conventions before writing new code

Troubleshooting

"Search index not available"

Your project is still being indexed. Run brain_status to check progress. Typically 2-5 minutes. Large monorepos (100K+ files) may take longer.

"No project specified"

Session expired or no repo_url provided. Include one in your next tool call.

Authentication not opening browser

• Restart your MCP client. Some clients only establish the OAuth handler on startup
• Check config for syntax errors. A missing comma can prevent connection
• Check your default browser. OAuth redirect depends on it being properly configured
• Try Claude Code CLI as a fallback to verify your account works

"Rate limit exceeded"

You've used all daily queries. Resets at midnight UTC, or upgrade for an immediate increase. Your data is preserved.

Tools not appearing

• Config file saved and valid. Even one extra comma breaks JSON
• Client restarted. Most read config only on startup
• Correct config path. See Quick Start
• URL is exactly https://api.altab.ai/mcp with no trailing slash

For Claude Code, verify with:

claude mcp list

Agent ignores Altab tools

Add the project configuration snippet from Best Practices. Without explicit routing, agents default to familiar built-in tools.

"Symbol not found"

• Indexing not complete. Check brain_status
• Name mismatch. Use search_definitions first to find the exact name
• Dynamic code. Symbols generated at runtime may not be detected

Private repositories

Altab can index private repos. GitHub authentication grants read access. Each user's data is fully isolated.

Supported languages

• Full support: Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, PHP, Swift, Kotlin, C#, Scala
• Search support: Any text-based file (config, docs, SQL, HTML, CSS, etc.)

Need more help?

Reach out at altab.ai/contact. For priority support, upgrade to Ultra or Max.