Skip to main content
AskMyDocs can serve as the project knowledge source for Codex, Claude Code, Claude web/Desktop, Cursor and compatible MCP clients. Each connection authorizes one company and one project, selected in the browser during OAuth consent. Another project gets another connection, plugin identity and MCP URL. You never copy API tokens, client IDs or secrets into the project.

​
Install and connect Codex

Open /mcp/connect on your AskMyDocs installation. Sign in, prepare a connection and download its plugin ZIP. Upload it in Codex under Plugins > New plugin. The archive contains plugin.json, mcp.json, .codex-plugin/plugin.json, .mcp.json and skills/ directly at the plugin root. It does not contain a marketplace catalog or an outer plugin/ directory. A marketplace archive is not a single-plugin upload. Operators can instead generate a local marketplace directory (a separate distribution format, not the ZIP upload):
In Codex, choose the plugin and Connect. OAuth opens AskMyDocs, where you sign in, select a company, select one project in that company, and approve the requested permissions. A single available company or project is preselected. An existing connection remains bound to its original project on reauthorization. Start a new chat/session after installing a local plugin so its bundled tools are loaded. Installation alone does not prove the account has authorized access. The browser login happens on AskMyDocs; Codex receives and stores the resulting OAuth tokens. Never enter an AskMyDocs password into a chat. For a direct Codex CLI connection, expand Connect through the Codex CLI on the setup page and copy the generated commands:
The login command opens or repeats the OAuth flow for that directly configured server. See the official Codex MCP commands and plugin installation guide. Clients that support adding an HTTP MCP server directly can use the unique URL shown by the setup page instead of installing the package. No bearer-token configuration is needed. The endpoint is:
The local marketplace is for local Codex clients. A public listing in the ChatGPT/Codex universal plugin directory requires submitting the deployed HTTPS MCP server through OpenAI’s plugin publishing and review flow; creating a local package does not publish it. A Herd .test endpoint is reachable from the local Mac, not from ChatGPT cloud execution.

​
Connect Claude and other clients

Open /mcp/connect, select the application, and prepare a connection. The page shows the unique URL and instructions for that client. Changing the application selector only changes instructions; OAuth identifies and authorizes the actual client. Prepare another connection for a different project. Separate connections per application also let you revoke each application’s access independently.

​
Claude web and Desktop

In Claude, open Customize > Connectors > Add > Custom > Web. Enter a name and the connection’s MCP URL. Choose Sign in now and Register automatically under OAuth client. AskMyDocs supports dynamic client registration; it does not currently support Claude’s published-identity/CIMD option. No manual client ID, client secret, bearer token or request header is required. Finish browser sign-in and select the company/project in AskMyDocs. These custom connectors connect from Anthropic’s cloud, including when used in Claude Desktop. They require a deployed public HTTPS AskMyDocs origin; the development address https://askmydocsdev.test is not reachable by Anthropic. See Claude’s connector setup and network requirements.

​
Claude Code

Run the command generated by /mcp/connect in your development project:
Then open /mcp in Claude Code and complete OAuth sign-in. The generated server name includes the connection UUID, so a second project has a different name as well as a different URL. A local installation requires that the machine running Claude Code can resolve the Herd domain and trust its TLS certificate. See Claude Code’s MCP documentation.

​
Cursor and other MCP clients

Select Cursor to copy a ready-to-use mcpServers JSON entry, with a unique server name and URL. Merge it into Cursor’s MCP configuration while preserving other servers, then enable the server and finish OAuth sign-in. Cursor supports Streamable HTTP and OAuth. Other clients need Streamable HTTP, protected-resource OAuth discovery and dynamic client registration. Use the connection URL, then complete browser sign-in. Clients supporting only local stdio or fixed bearer-token authentication cannot use this OAuth endpoint directly. The same search, read and ingest tools are exposed in every client. A client’s ability to send local files or attachments depends on its file-access features; the ingest tool accepts file content, not a path on the user’s computer. Server tests cover registration, PKCE, consent, token exchange and project reads with HTTPS, IPv4, IPv6 and exact localhost callbacks, including changing local ports and rejecting host/path/query substitutions. UI tests cover the client instructions and generated configurations. These tests do not claim that a real Claude or Cursor account has completed sign-in; that requires the deployed origin and an end-to-end check in the chosen client.

​
Search and read

The connected server exposes these tools: Search and document tools have no tenant or project argument. Every request rechecks account activity, membership in the selected project, current client policy, token audience, expiry and revocation. Reading a document by its numeric ID cannot escape the selected project. Existing document access scopes apply. The PHP surface is ConnectedProjectWorkspace / McpDocumentImportService. The REST adapters are POST /mcp/knowledge/{connection}/api/info, /search, /document and /imports; they use the same OAuth authority and services.

​
Send documents from Codex

Ask Codex to import specific local files. It can send Markdown and plain text as text, or PDF/DOCX bytes as base64. One call accepts at most ten files, 5 MB per decoded file and 10 MB total. File signatures are checked. Arbitrary filesystem paths and download URLs are not accepted as file content.
  1. Codex submits the files to kb-ingest-documents-tool.
  2. AskMyDocs stages them and returns the import ID, file manifest and approval_url. The files have not been indexed yet.
  3. Open that link. Review the destination, names, sizes and text previews, then approve indexing. The MCP token cannot approve the operation itself.
  4. Codex polls kb-import-status-tool. Only ready: true means every file was indexed successfully and can be used for retrieval.
The import capability requires mcp:ingest plus the existing admin/super-admin ingestion role and unrestricted membership in the selected project. Read-only connections use mcp:read. Uploads use a separate content-addressed source namespace, preserving existing source files. Identical retries return the original import, including concurrent submissions. Approval is valid for one hour and is bound to the staged byte hashes; changed staged files are rejected. The queue rechecks the initiating user’s current permissions before processing. The import delegates to KbUploadStagingService and IngestDocumentJob, the same conversion, chunking, PII handling, embedding and persistence pipeline used by existing uploads. It does not implement a second document index.

​
Authentication and deployment

Protected-resource discovery is available at /.well-known/oauth-protected-resource/mcp/knowledge/{connection}. An unauthenticated MCP request returns a WWW-Authenticate challenge pointing at that exact resource metadata. The MCP authorization-server issuer is APP_URL/oauth/mcp, discovered at /.well-known/oauth-authorization-server/oauth/mcp. The existing authorization server provides public-client dynamic registration, authorization codes with mandatory S256 PKCE, issuer-bound callbacks, resource audience validation and refresh-token rotation. Access tokens last at most one hour (or the shorter Sanctum lifetime). Refresh families expire 90 days after consent; replaying a consumed refresh token revokes its family. Browser approval and connection management require a session and CSRF protection. The legacy /mcp/kb tenant-token endpoint and the existing API OAuth clients keep their separate authentication contracts. Deploy the migration and frontend build:
laravel/mcp is a production dependency. Use the installation’s public HTTPS APP_URL, keep its queue worker running, and use a shared lock-capable cache store across workers. Dynamic registration and MCP traffic have independent rate limits. Tokens are hashed at rest; tool audit records omit document bodies and secrets. Revocation is available at /oauth/connections. See OpenAI’s MCP authentication and plugin packaging guides for client installation and public distribution.