AI AGENTS + MCP

Connect your AI agent.

MCP (Model Context Protocol) connects your AI agent to Research Tab so it can work with your research through conversation. Explore shared evidence and update research records with the access you choose.

Set up your connection

What will you ask first?

“List my project’s open tasks.”
“Create an experiment and record these run results.”
“Compare these runs and create a preliminary finding linked to the evidence.”
“Read this paper’s source and supporting findings.”
“Upload this PDF as a project report.”

Connect in three steps.

Choose your access
Sign in and open API Access. Create a Read only token for inspection, or a Project automation token for research edits. Select your project and an expiry. You need access to that project.
Configure your agent
Use a client that supports remote MCP over Streamable HTTP with bearer-token authentication. Store the token in your local secret or environment setup. Never paste it into a conversation, source control, or a URL.
Codex configuration
Make RESEARCHTAB_API_TOKEN available in the environment of the process running Codex. Add this to your user configuration at ~/.codex/config.toml:
```
[mcp_servers.researchtab]
url = "https://researchtab.com/api/v1/mcp"
bearer_token_env_var = "RESEARCHTAB_API_TOKEN"
```
Restart Codex with that environment available and open a new task. Each machine or execution host needs its own configuration and credential.
Official Codex MCP documentation ↗
Other compatible clients and self-hosted installations
Transport
Streamable HTTP
Endpoint
https://researchtab.com/api/v1/mcp
Authentication
Bearer token in the Authorization header, supplied through your client’s secret settings.
For self-hosted installations, replace the API origin and keep /api/v1/mcp. Research Tab currently uses personal API tokens; OAuth browser login is not available. A client that only supports OAuth cannot use this connection.
Test with a read
Ask: “Call get_capabilities, then read my authorized project and list its open tasks.” Confirm the project and available tools before requesting edits.

From a question to a finding.

With a Project automation token, ask your agent to compare two existing runs. It reads their results, creates a preliminary finding, and links the evidence. Open Research Tab to inspect the finding; verification remains a human decision.

Your AI agent

Compare these runs and create a preliminary finding.

Read results · Compare evidence

Research Tab

Preliminary

Finding linked to both runs

Run A

Run B

Awaiting human verification

Illustrative workflow · Scoped access · Audited changes · Human decisions

You choose the access.

Your agent can

Read permitted shared research, tables, metrics, supported artifacts, and paper source. With write access, it can apply supported routine edits, record experiments and runs, create preliminary findings, and upload reports.

Decisions stay with people

MCP cannot verify findings, accept review decisions, grant access, or manage credentials and billing. It cannot execute local commands or disclose local drafts.

Authorized writes apply immediately and are audited. They are not held in a Research Tab approval queue. Your current permissions and the token’s scope both apply on every call.

Revoke tokens in API Access whenever you need to stop future calls. Revocation cannot recall data already retrieved by your agent. Use separate project-scoped tokens and connections for different projects.

If something does not connect.

Connection fails or reports unauthorized

Check the endpoint and confirm your client supports Streamable HTTP and bearer tokens. Ensure the token is available to the running agent process, has not expired or been revoked, and belongs to a user with current project access. Restart the client after changing its environment. Opening the endpoint in a browser is not a connection test; browser GET requests return 405.

A tool or project is missing

Ask the agent to call get_capabilities. Tools reflect the token’s capabilities. Read only tokens cannot edit, and run-scoped tokens cannot read a whole project. Check the selected project and your membership. A group project-creator token only creates projects; create a project-scoped token in API Access for later work.

An edit reports a conflict

Ask the agent to reread the record and use its current version before retrying the edit. Review the intervening changes first.

A request times out or is rate limited

After an uncertain create or upload, check whether the record already exists before retrying. For rate limits, respect the server’s Retry-After response.

Open API Access Back to Research Tab